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Preface 


This    manual    describes    the    FMS   1 1    Software    Systerr    for   use    with    the 
RSX-llM.  RSX-UM-FLrS,  and  IAS  operating  systems.  Overview  sections    | 
tell  how  FMS   11  components  work  together.  Detailed  sections  introduce  the 
features  ol' each  component. 

This  manual  and  FMS   1 1  software  are  primarily  for  HSX   llM/M   FLl'S  and 
IAS    svstem     programmers    who    have    experience    with    BASIC   FLl'S-2.     | 
COBOL  11.   FORTRAN   IV.   FORTRAN   IV  FLl'S.   and   MACRO   11    pro- 
grams. 

The  next  section,  (^hapter  Summary,  briefly  describes  the  chapters  in  this 
manual  and  is  followed  l)y  a  separate  section  that  describes  the  documenta- 
tion conventions. 

CHAPTER  SUMMARY 

Chapter  1  introduces  (orm  processing  and  presents  general  information  about 
the  FMS  11  software  components. 

Chapter  2  describes  the  FMS  1 1  Form  Editor  in  detail.  The  Form  P^ditor  is 
the  FMS  1 1  component  that  creates  and  modifies  computerized  form  descrip- 
tions for  later  use  in  form  applications. 

Chapter  3  describes  the  FMS- 1 1  Form  Utility  in  detail.  The  Form  Utility  is  a 
system  utility  for  manipulating  form  descriptions  by  creating  form  lii)rary 
files,  printable  files  that  show  how  forms  have  been  designed,  object  modules 
for  forms,  and  directories  oi  library  files. 

Chapters  4,  5.  6.  and  7  introduce  and  describe  the  FMS- 11  Form  Driver.  The 
Form  Driver  is  the  FMS-11  component  that  displays  forms  and  accepts  data 
that  operators  type  in  response  to  the  forms. 

Chapter  4  introduces  Form  Driver  concepts  in  two  major  sections: 

1.  How  the  Form  Driver  interacts  with  the  form  descriptions  that  you  have 
created  with  the  Form  Editor. 

2.  How   the   Form   Driver  interacts   with   the  terminal  operator  when  an 
FMS  1 1  application  is  running. 

The  section  about  interaction  with  the  form  description  includes  detailed 
descriptions  of  how  the  Form  Driver  treats  the  field  attributes  and  form  at- 
tributes. The  section  about  interaction  with  the  terminal  operator  includes 
deJ.  '\1  descriptions  of  error  handling,  the  lield  editing  functions  that  an 
oper^jior  can  use.  and  the  ways  an  operator  can  terminate  input  in  fields  and 
forms. 

Chapter  5  presents  programming  requirements  and  concepts.  The  first  major 
section  presents  requirements  that  apply  l(t  all  programming  languages.  Then 
separate  sections  l<.r  BASIC  PUS  2.  COBOL  11.  FORTRAN  IV  and 
FORTRAN  IV  IMAS.  and  MACRO  1 1  present  the  special  details  that  apply 
only  to  each  of  those  languages. 
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Chapter  6  is  the  main  reference  chapter  lor  the  Form  Driver  calls.  Detailed 
descriptions  of  the  calls  are  arranged  in  alphabetical  order  by  the  high-level 
language  call  name.  P'.ach  description  is  organized  as  follows: 

1.  The  purposes  and  effects  of  the  call  -  This  information  applies  to  all 
programming  languages. 

2.  The  forms  of  the  call  —  For  each  high-level  language,  the  general  forms  of 
the  CALL  statement  are  given  in  full  with  argument  abbreviations  that 
stand  for  the  purposes  of  the  arguments.  For  MACKO-11.  the  general 
form  of  the  macro  call  to  the  Form  Driver  ($FDV)  is  given. 


3. 


The  input  and  output  arguments  —  The  required  and  optional  inputs 
and  outputs  for  the  call  are  listed  in  tables  that  show  the  argument  abbre- 
viations and  explain  the  requirement  on  input  or  the  value  on  output.  This 
information  applies  to  all  programming  languages. 


4. 


The  codes  and  values  for  the  status  of  the  call 
status  values  and  the  bles. 


The  high-level  language 


Chapter  7  presents  programming  techniques  that  illustrate  special  P^)rm 
Driver  capabilities  and  show  useful  combinations  of  Form  Driver  calls.  F'.xam- 
ples  in  the  high-level  languages  and  MACHO-11  are  included. 

Chapter  8  describes  how  to  prepare  your  system  for  FMS  applications.  Sepa- 
rate sections  cover  the  relevant  RSX-  11  system  generation  oj)tions.  FMS  11 
instillation  procedures,  the  FMS  11  configuration  procedure  for  the  Form 
Driver,  including  a  full  listing  of  the  interactive  configuration  dialogue,  and 
IAS  procedures  for  running  FMS  11  applications. 

Three  appendixes  supplement  the  manual.  Appendix  A  contains  a  listing  of 
the  FMS  11  svstem  macro  library  (FMSMAC.MAC),  Ai)pendix  B  contains 
listings  of  executable  examples  of  FMS-11  that  DICITAL  has  distributed  as 
part  of  your  kit.  Appendix  C  lists  and  explains  all  of  the  FMS   1 1  messages. 

Symbols  and  Conventions 

This  manual  and  the  FMS  IJ/RSX  Mini-Ri'fcrcuvv  use  the  following  symbols 
and  conventions.  Although  most  of  them  are  the  same  as  the  symbols  and 
cojiventions  used  in  other  documents  for  PDP  11  soltware.  the  \'Tl(M»  termi- 
nal and  the  video  orientation  of  the  keypad  editor  require  a  few  changes. 


System  prompts 


Hed  |)rint 


Indicate  that  the  system  is  ready  for  you  to  enter  a 
command.  The  system  prompts  an: 

For  KS\  llM:  the  characters  MCR  or  a  right-angle 
})riicket  ( ) )  by  itself. 

For    KSX   IIM   PLCS:    the    dollar    sign    (♦)    or    the 
HSX   llM  prompts  (when  the  MCli  is  running). 
For  IAS:  the  characters  PDS     or  MCR    . 

Indicates  the  chara-.-ters  typed  on  the  keyl)oard  in  ex- 
amples of  commands,  lilack  print  in  these  examples 
indicates  the  characters  dis|)laye(i  by  the  system  or  by 
the  FMS   11  soltware. 
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Uppercase  letters 
(In  commands 
and  calls) 


Indicate  the  characters  that  you  must  type  on  the  key- 
board (see  "Lowercase  letters"  also). 


Lowercase  ?°tters 
(In  commands 
and  calls) 


Indicate  the  parts  of  commands  or  command  strings 
that  you  must  supply  (see  "Uppercase  letters"  also). 


(EfRiTI 


Indicates  a  combination  of  the  control  key  and  another 
keyboard  key.  For  example,  for  tiRLu]  hold  down  the 
CTRL  key  and  press  the  U  key. 


Square  brackets  [ 
(In  general  forms 
of  commands) 


Braces 


Enclose  an  optional  term  or  optional  characters  (do  not 
type  square  brackets  as  part  of  a  command  unless  the 
instructions  explicitly  require  them). 

Enclose  a  list  of  two  or  more  terms  from  which  you 
must  choose  and  type  one  (do  not  type  braces  as  part  of 
a  command). 


Dot  matrix  letter?       Indicate  prompts,  short  status  messages,  and  exanaples. 
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Chapter  1 

INTRODUCTION  TO  FMS-11 


1.1    Overview 


FMS-11  is  digital's  Form  Management  System.  FMS-11  software  contains 
the  tools  for  developing  form  applications  and  running  them  on  VTIOO  termi- 
nals. Printed  forms  have  been  the  most  common  tool  for  collecting  and 
transmitting  data  in  an  orderly  manner.  FMS-11  software  now  brings  the 
speed,  convenience,  accuracy  and  low  cost  of  computerized  processing  to  users 
who  have  been  using  printed  forms. 

FMS-11  was  previously  available  only  on  RT-11  systems.  The  FMS-11  soft- 
ware described  in  this  manual  is  designed  to  run  on  RSX-llM,  V3.2, 
RSX-llM-PLUS.  VI. 0,  and  IAS,  V8.1  systems  for  user  application  develop- 
ment and  execution.  In  addition,  many  FMS-11  application  programs  devel- 
oped for  RSX-1  M  or  RSX-llM-PLUS  systems  can  be  executed  on 
RSX-US.  V2.2. 

Forms  are  designed  by  typing  them  directly  onto  the  termmal  screen.  Neither 
layout  charts  nor  a  special  forms  design  language  are  required.  FMS-11  asso- 
ciates constant  data  with  the  form,  not  with  the  application  program,  result- 
ing in  simplified  application  program  maintenance  and  increased  application 
program  flexibility.  Forms  can  later  be  modified  without  the  need  to  recom- 
pile the  application  program. 

Form  application  programs  can  be  written  in  one  ot  several  programming 
languages.  FMS-11  provides  language  sup|)(»rt  for  COBOL- 11, 
BASir-PLUS-2,  FORTRAN  IV,  FORTRAN  IV  PLUS,  and  MACRO  11. 

FMS-11  software  has  three  main  components  for  developing  and  executing 
form  application  programs: 

•  The  Form  Editor  (FED) 

•  The  Form  Utility  (FUT) 

•  The  Form  Driver  (FDV) 


1.1.1    The  Form  Editor 

The  Form  Editor  (FED)  simplifies  designing,  modifying,  and  storing  form 
descriptions  for  video  display.  Your  screen  always  shows  the  current  state  of 
the  form  you  are  working  on.  Keypad  and  keyboard  functions  provide  ways  for 
you  to  specify  video  display  characteristics  for  constant  text  or  fields  that 
contain  picture  characters.  To  help  operators,  you  can  include  in  the  form 
descriptions  short,  helpful  explanations  about  individual  fields  and  about 
each  form  as  a  whole. 
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When  designing  forms,  you  assign  form  names,  field  names,  and  refer  to  data 
that  will  he  used  (but  not  displayed)  by  the  Form  Driver  when  the  form  is 
used  by  an  application  task.  The  desired  operator  response  to  information 
displayed  or  data  to  be  entered  on  forms  is  controlled  by  the  actual  design  of 
the  form  and  the  specific  application  task  requirements. 

1.1.2    The  Form  Utility 

The  Form  Utility  (FUT)  allows  you  to  create  versions  of  form  descriptions 
that  are  suitable  for  hard-copy  listings,  to  create  and  modify  form  libraries,  to 
list  the  names  of  forms  contained  in  a  form  library,  and  to  produce  object 
modules  of  form  descriptions.  You  can  task  build  the  object  modules  with 
form  application  code  to  produce  form  applications  that  are  entirely  memory- 
resident.  The  Form  Utility  also  generates  COBOL  data  division  code  suitable 
for  copying  into  a  COBOL  task  to  correspond  to  a  form  definition. 


1.1.3    The  Form  Driver 

The  Form  Driver  (FDV)  is  a  set  of  subroutines  that  permits  your  application 
program  to  access  forms  that  you  created  using  the  Form  Editor.  Application 
programs  access  forms  by  issuing  Form  Driver  calls  that  are  imbedded  in  the 
task  and  are  written  in  the  source  language  of  the  task.  All  Form  Driver  calls 
refer  to  specific  forms  and/or  fields  within  forms  using  names  that  you  as- 
signed during  the  form  editing  process.  The  Form  Driver  performs  field  and 
character  validation  for  operator  input  based  on  the  form  definition  (valida- 
tion is  based  on  picture  validation  characters  and  field  attributes).  The  Form 
Driver  also  responds  to  operator  HELP  requests  by  displaying  appropriate 
help  text  associated  with  the  form  and  field  being  processed. 


1.2    Developing  Form  Applications 

Seven  stages  comprise  the  typical  development  cycle  for  form  application 
programs: 

•  PLAN 

Study  the  existing  process  that  the  FMS-U  application  will  improve;  list 
the  data  thai  operators  can  provide;  list  the  hardware  resources  that  opera- 
tor sites  will  have;  describe  the  skills  that  operators  have  and  the  additional 
skills  they  will  need;  specify  the  features  that  FMS  11  forms  for  the  api'i- 
cation  are  to  have  and  the  processes  that  the  form  application  programs  are 
to  perform. 

•  DESKIN  FORMS 

Use  the  Form  PMitor  to  lay  out.  and  modify  the  forms  that  the  form  applica- 
tion programs  will  use;  use  the  Form  Utility  to  print  form  descriptions  for 
reference,  to  create  (ibject  modules  for  form  descriptions  that  are  to  be 
memory  resident,  to  store  forms  in  a  lorni  library  file,  and  to  list  the  names 
of  forms  that  art  in  a  form  library  file. 
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•  WRITE  TASKS 

Use  the  Form  Driver  calls  in  the  form  application  task  to  process  form 
descriptions,  to  handle  form-related  terminal  I/O,  and  to  check  the  validity 
of  operator  responses  (to  a  limited  extent). 

•  DEBUG  TASKS  WITH  FORMS 

Confirm  that  all  processes  that  use  the  application's  forms  work. 

•  VALIDATE  ON  OPERATOR  SITE  SYSTEMS 

Confirm  that  the  forms  and  application  program  software  work  on  each  type 
of  target  system  on  which  it  will  be  used. 

•  PREPARE  APPLICATION  SYSTEM  DOCUMENTATION 

Provide  complete  documentation  for  operators  who  will  use  the  FMS-U 
forms  and  application  program  software. 

•  DISTRIBUTE 

Package  and  distribute  the  FMS-U  forms,  application  program  software, 
and  user  documentation  as  a  complete  application  system  package. 

The  two  major  stages  required  when  developing  form  applications  are  de- 
signing forms  and  writing  application  programs.  Chapter  2  contains  the  infor- 
mation that  you  will  need  in  order  to  design  and  modify  forms.  After  forms 
have  been  designed,  the  Form  Utility  helps  you  to  create  and  maintain  form 
library  files;  the  Form  Utility  is  described  in  detail  in  Chapter  3. 

The  application  program  writing  stage  deals  with  the  use  of  the  Form  Driver. 
Details  for  writing  Form  Driver  application  programs  are  contained  in  Chap- 
ters 4  through  8.  These  chapters  include  information  on  Form  Driver  interac- 
tion between  forms  and  the  operator  as  controlled  by  Form  Driver  calls  issued 
by  the  application  program,  application  programming  requirements  and  con- 
cepts. Form  Driver  interface  to  various  programming  languages,  the  Form 
Driver  calls,  programming  techniques  and  examples,  and  building  and  run- 
ning form  application  programs. 
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Chapter  2 

The  FMS-11  Form  Editor  (FED) 


2.1  Overview 

The  FMS-11  Form  Editor  allows  you  to  create,  modify,  and  store  customized 
forms.  Your  application  programs  can  then  use  these  forms  to  collect  data 
entered  by  an  ojerator  at  a  video  terminal. 

Creating  or  editing  a  form  with  the  Form  Editor  is  an  interactive  and  iterative 
process.  You  do  not  need  to  know  in  advance  all  the  details  or  all  the  modifi- 
cations that  you  intend  to  specify  for  a  form.  The  Form  Editor  lets  you  test 
various  possibilities,  observe  their  appearance  on  the  screen,  and  choo.se  the 
design  that  you  consider  most  successful. 

The  product  of  your  work  with  the  Form  Editor  is  a  form  description  that  can 
be  saved  in  a  file  or  form  library.  The  form  description  can  be  retrieved  from 
the  file  or  form  library  for  additions  or  changes.  You  can  change  individual 
fields  or  text  portions  of  the  form  without  affecting  other  fields  or  text. 

For  example,  you  might  want  to  translate  the  text  of  a  form  into  another 
language,  reposition  items  on  the  screen  to  make  the  form  more  attractive  to 
the  eye  or  easier  for  an  operator  to  handle,  add  or  remove  fields,  or  supply 
additional  help  text.  You  can  make  these  and  other  changes  by  calling  the 
Form  Editor,  editing  the  screen  image  of  the  form  to  make  the  desired  changes 
in  the  form  description,  and  saving  the  modified  form  description  in  the  file  or 
form  library. 

The  purpose  of  the  form  description  is  to  provide  information  to  another 
software  component  called  the  Form  Driver.  The  Form  Driver  handles  the 
interaction  of  the  terminal  operator  with  the  form  displayed  on  the  screen  and 
with  the  application  program.  The  F'orm  Driver  is  described  in  Chapter  4. 

In  summary,  the  Form  P^ditor  allows  you  to  perform  these  operations: 

1.  Creation  and  modification  of  a  form's  screen  image  by  means  of  the  termi- 
nal's main  keyboard  and  the  text  editor  keypad. 

2.  Storage  of  form  descriptions  in  files  and  form  libraries,  and  retrieval  of  the 
files  from  those  libraries. 

2.2  Form  Editor  Terminology 

2.2.1    Screen  Form 

The  screen  Ibrm  looks  like  a  paper  form,  but  is  a  video  display  instead.  The 
computer  forms  the  display  by  using  a  form  descri|)tion  that  s[)ecifies  to  the 
computer  which  characters  to  display  on  the  screen. 
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2.2.2  Form  Description 

The  form  description  is  a  computerized  specification  of  a  screen  form.  It 
specifies  which  characters  to  display  on  the  screen  as  well  as  the  location,  size 
and  other  characteristics  of  each  field.  The  name  of  the  Ibrm  and  how  the 
form  and  its  fields  are  pn)cessed  are  also  part  of  the  specifications. 

2.2.3  Fieid 

The  field  is  a  set  of  contiguous  characters  (either  picture-validation  or  field - 
marker)  terminated  hy  a  hlank,  a  non-field  character,  an  end-of-line  delimiter 
or  a  change  in  video  attrihutes.  A  field  is  a  formatted  hlank  for  some  of  the 
information  that  a  form  has  been  designed  to  work  with. 

2.2.4  Form  Description  Fiie 

The  form  description  file  is  a  computer  file  that  contains  only  one  form  dt 
script  ion  which  may  or  may  not  be  complete  or  accurate.  It  is  a  binary  fiK 
that  has  been  arranged  so  FMS  can  use  it  to  display  screen  forms. 

2.2.5  Form  Library  File 

The  form  library  file  is  a  computer  file  containing  at  least  one  form  descrip- 
tion and  a  directory  of  the  names  for  each  form  description.  It  is  a  binary  file 
but  is  arranged  so  individual  form  descriptions  can  be  taken  out  by  name  for 
u.se  bv  FMS. 


2.3    Star*!^ig  the  Form  Editor 


Th<=  Form  Editor  (FKD)  requires  a  VTUK)  terminal.  The  terminal  must  be 
made  known  to  the  system  as  a  VTIOO. 

RSX  IIM/M  FLl'S  users  can  use  the  \\V\:  SET  command  for  this: 

SET     . VT 100=TI : 

or 

SET     .''TERM  =  T  I  :'.'T100 

(The  RSX  MCR  Operations  Manual  gives  the  SET  command.) 

IAS  \)C\.  users  can  identify  a  VTIOO  terminal  with  the  command: 

SET   TErvMINAL  VT  100 

(The  IAS  I'DS  I'scr's  Ciiidc  describes  the  SET  command.) 

IAS  MCH  users  can  identify  a  VTIOO  terminal  with  the  command: 

TEfy  .''.'TlOO 

(The  IAS  MCR  I'scr's  Cuidr  describes  the  TEH  command.) 

The  Form  Editor  requires  the  full  duplex  ternnnal  driver  to  run. 
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The  main  keyboard  performs  normally  when  you  are  usinp  the  Form  Editor, 
providing  you  with  a  means  to  insert  characters,  delete  them,  and  so  on.  The 
keypad  to  the  right  of  the  keyboard  provides  operations  specifically  related  to 
the  Form  Editor. 

The  following  operations  are  used  to  design  a  form: 

•  Starting  the  Form  Editor 

By  using  the  standard  commands  to  load  the  Form  Editor  into  memory,  you 
begin  program  execution. 

When  the  Form  Editor  prompt  (FED  ■  )  is  displayed  on  the  screen,  you  may 
type  in  a  response.  The  response  describes  the  form  file  that  you  want  to 
create  or  edit,  or  the  library  that  contains  the  desired  form.  The  response 
requires  a  prescribed  syntax  (that  will  be  described  in  the  "File  Specifica- 
tion" section). 

To  start  the  Form  Editor  ii       is  in  the  system  account,  type: 

RUN  $FED  (RET) 

The  Form  Editor  clears  the  screen,  displays  the  prompt  FED  >  at  the  bottom 
of  the  screen  and  accepts  a  command  line. 

If  the  Form  Editor  is  installed  on  your  system,  you  can  start  it  by  typing: 

FED® 

IAS  users  can  run  the  Form  F^ditor  from  MCR  or  MCR  mode.  To  start  the 
P\)rm  Editor  on  IAS,  for  example,  your  c(;mmand  line  should  be  either 

MCR>FED  (for  MCR  users) 

or 

PDS  >  >FED  (for  DCL  MCR- mode  users) 

In  other  examples  for  IAS,  only  the  MCR  command  lines  will  be  shown. 

The  Form  Editor  is  built  with  buffer  space  that  should  be  sufficient  to  edit 
almost  any  form.  It  will  allow  you  to  create  or  edit  a  form  descripticm  2048 
words  in  length. 

However,  if  you  are  editing  forms  larger  than  2048  words  or  are  editing  forms 
smaller  than  that,  you  may  wish  to  change  ths  size  of  the  FED  task.  FED 
can  be  installed  or  run  w-th  a  different  task  increment: 

For  rtSX-llM  and  IlM-PLUS  sy.stems  -  | 

INS    tFED/INC  =  N'or(/.s 


or 

RUN    $FED/ INC  =  frorc/.s 

For  IAS  systems  - 

INS  L  1  1  »1  ]FED/  INC  =  uorti.s 


I 
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The  default  task  extension  FED  is  built  with  4096  words.  The  minimum 
extension  required  for  FED  to  run  is  1024  words. 

•  Issuing  Form  Editor  Commands 

You  can  use  any  of  several  commands  to  enter  a  particular  phase  of  the 
Form  Editor.  Table  2-1  summarizes  the  commands.  You  type  the  com- 
mands in  response  to  the  COMMAND:  prompt.  If  you  type  HELP  in  re- 
sponse to  the  COMMAND:  prompt,  the  Form  Editor  displays  the  valid  re- 
sponses to  the  prompt. 

Table  2-1:    FED  Command  Summary 


Command 


Abbreviated 
Command 


EDIT 

ASSIGN  [optwn] 


ED 


where  uptian  can  be  one  of 
the  following: 

ALL 


ne:w 

FIELD  fldnam 
FORM 


A  A 


AN 


A  F  fidnnm 
F 


HELP 
NAME 


H 

N 


SAVE 


Qi;iT 


(None) 


(None) 


Function 


Create  or  edit  the  form's  screen 
image. 

Assign  field  attributes.  ("At- 
tributes" are  characteristics  of 
fields  that  you  assign  with 
FED  for  use  by  the  P'orm 
Driver.) 


Assign  attributes  for  old  and 
new  fields. 

Assign  attributes  for  newly  cre- 
ated fields. 

Assign  attributes  for  the  par- 
ticular field  called  fldnam. 

Assign  form-wide  attributes. 
(Form-wide  attributes  are  at- 
tributes that  apply  to  an  entire 
form  rather  than  a  particular 
field.) 

Lists  the  commands  available 
in  the  form  editor. 

Enter  and  edit  named  data. 
(Named  data  is  information 
that  is  to  be  associated  with  a 
torm  but  not  displayed  with 
it.) 

St(»re  the  completed  form  and 
return  to  the  FED  prompt. 
Both  in|)ut  and  output  files  are 
preserved. 

(^ancel  the  current  session 
without  saving  outi)Ul  files  and 
return  to  the  FED  prompt. 
The  input  file  is  preserved. 
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•  Using  Keypad  Operations 

The  keypad  layout  for  the  Form  Editor  in  Figure  2-1  shows  the  operations 
that  are  associated  with  certain  keys  or  key  combinations. 

Figure  2-1:    FED  Keypad  Layout 
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•  File  Specifications 

The  Form  Editor's  output  always  goes  to  a  form  file.  A  form  file  contains 
only  one  form  description.  (To  create  or  update  form  libraries  use  the  Form 
Utility  (FUT)  described  in  Chapter  ;^). 

To  create  a  new  form,  use  the  /CR  option: 

FED  ^     CR® 

To  edit  a  form  contained  in  a  form  file,  type  the  name  of  the  form  file,  for 
example  "VENDOR". 

FED>'.'ENDQryilTj 

To  extract  a  form  from  a  form  library  for  editing,  type  the  name  of  the  library 
file  and  respond  to  FED's  "Form  name'^"  prompt  with  the  name  of  the  form. 
The  default  file  type  is  .FRM  indicating  a  form  file.  If  it's  .FLB.  you  must 
type  .FLB  explicitly: 

FED>DEMLlB.FLB;REr) 
"Form    r.ame'^"    FirvST® 


If  the  specified  form  is  not  found,  FED  repeats  the  "Form  pame'?'  prompt. 
If  you  press  the  iEj)  key  in  response  to  the  "Form  name?"  prompt.  FED 
displays  the  FED     prompt  again  and  waits  for  a  new  command  line. 
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It  isn't  necessary  to  distinguish  a  form  file  from  a  library  file  on  the  command 
line.  FED  determines  whether  the  input  file  is  a  form  file  or  a  library  file,  and 
proceeds  accordingly. 

If  you  want  to  know  the  version  number  of  the  Form  Editor  you  are  using,  you 
can  ask  the  Form  Editor  to  display  its  identification  message  by  typing: 


I 


FED)-/  ID® 

File  specification  formats  differ  slightly  according  to  the  operating  system  you 
use. 

The  syntax  for  RSX-llM/M-PLUS  form  file  and  library  file  specifications  is: 

dev:[UIC]filename.  type;version 

The  syntax  for  IAS  form  file  and  library  file  specifications  is: 

dcv:[l  'FI)]filcname.  typcwersion 

If  the  device  is  not  specified  for  the  input  file.  FED  assumes  the  system 
device.  For  RSX,  if  the  UIC  (User  Identification  Code)  is  omitted,  FED  de- 
faults to  the  currently  assigned  UIC.  For  IAS,  FED  defaults  to  the  existing 
default  UFD. 

The  default  file  type  for  the  input  file  is  FRM  (a  form  file).  If  an  explicit 
version  number  is  not  specified  for  an  input  file,  FED  uses  the  latest  versi(m  of 
the  file. 

The  output  file  that  FED  creates  during  an  editing  session  is  always  a  form 
file  with  the  file  specification  "/orm. FRM".  ''Form''  is  the  name  of  the  form 
when  the  session  ends.  On  RSX-llM  and  RSX-UM-PLUS,  FED  creates  the 
output  tile  on  the  system  device  in  the  RSX  account  under  which  the  Form 
Editor  is  running.  On  IAS,  FED  creates  the  output  file  in  the  existing  default 
UFD. 


2.4    Form  Editor  Commands 


You  can  type  any  (me  of  the  commands  shown  in  Table  2-1  (The  FED  Com- 
mand Summary)  in  response  to  the  COMMAND:  prompt.  The  P'orm  Editor 
enters  th"  specified  command  after  you  press  the  ENTER  key  on  the  keypad. 
If  you  want  to  cancel  your  last  command,  type  the  ^Ty]  combination  before 
you  press  the  ENTER  key.  If  you  want  to  change  a  command,  use  the  ®  key 
to  delete  the  characters  that  make  up  the  command.  You  can  use  ^iM>  to 
delete  the  entire  command  line  and  then  type  in  a  new  command. 

You  can  type  the  HELP  command  to  display  a  list  of  the  Form  Editor  com- 
mands and  their  functions. 

Begin  an  editing  session  with  a  rough  pencil  sketch  of  the  form  that  you  want 
to  create.  You  can  elaborate  the  details  of  the  form  interactively  with  the 
Form  Editor  by  looping  back  through  the  command  functions  (by  means  of 
the  CiOLD/COiviIVlAND  key  sequence)  and  adding  or  deleting  features  gradu- 
ally during  the  development  of  the  form  design. 
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The  various  command  operations  let  you  control  the  phases  of  your  work 
during  a  iorrn  editing  session  and  to  move  in  an  orderly  manner  from  one 
phase  to  another.  Any  phase  can  be  entered  at  any  time.  The  FORM,  AS- 
SIGN, and  NAME  phases  u^e  the  Form  Driver  to  display  and  collect  re- 
sponses with  questionnaire  forms. 

Form  Driver  key  operations  are  active  while  you  are  completing  any  of  the 
questionnaires.  For  example,  when  you  are  assigning  form-wide,  field,  and 
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named  data  attributes,  the  TAB  key  has  the  effect  of  moving  the  curso.  *o  the 
first  character  position  of  the  next  field,  and  the  BACKSPACE  key  moves  ti.. 
cursor  to  the  previous  field.  Chapter  4,  on  Form  Driver  interaction  with  the 
terminal  operator,  describes  Form  Driver  key  operations  in  detail. 

2.4.1  Assigning  the  Form-Wide  Attributes:  The  FORM  Command 

FORM  places  you  in  the  Form-wide  Attribute  Questionnaire.  The  Form  Edi- 
tor displays  a  questionnaire  that  collects  the  necessary  information  from  you 
to  create  a  form  file. 


2.4.2  Editing  the  Form  Dispiay:  The  EDIT  Command 

EDIT  causes  the  Form  Editor  to  enter  the  EDIT  phase.  In  EDIT  you  create 
and  modify  the  screen  image  of  the  form.  You  may  type  background  text, 
create  fields  and  scrolled  areas,  and  assign  some  kinds  of  attributes.  Use  the 
GOLD/COMMAND  key  sequence  to  return  to  the  COMMAND:  prompt. 

2.4.3  Assigning  the  Fieid  Attributes:  The  ASSIGN  Commands 

ASSIGN  with  any  of  its  options  tells  the  Form  Editor  to  enter  the  field 
attribute  assignment  phase.  When  the  form  is  a  new  one,  you  usually  type 
ASSIGN  after  completing  the  EDIT  phase.  For  each  field  in  the  form,  the 
Form  Editor  displays  a  questionnaire  that  requests  field  attributes.  If  you  are 
editing  an  existing  form,  you  only  need  to  fill  in  field  attributes  that  weren't 
assigned  earlier. 

If,  during  the  ASSIGN  phase,  you  wish  to  exit  before  completion  of  all  field 
attribute  assignments,  press  the  period  (.)  key  on  the  keypad.  This  action 
returns  you  to  the  COMMAND:  prompt  and  assigns  default  attributes  to  all 
remaining  fields. 

2.4.3.1  For  All  Fields:  The  ASSIGN  ALL  Command  —  Causes  the  Form  Editor 
to  request  attributes  for  all  fields.  To  display  the  questionnaire  for  the  next 
field,  press  the  ENTER  key. 

2.4.3.2  For  New  and  Changed  Fields  Only:  The  ASSIGN  NEW  Command  — 

Causes  the  Form  Editor  to  request  attributes  for  new  fields  only.  To  display 
the  questionnaire  for  the  next  field,  press  the  ENTER  key. 

2.4.3.3  For  a  Specified  Field  Only:  The  ASSIGN  Field  Command  —  Followed  by 
a  field  name,  allows  you  to  assign  attributes  to  the  particular  field  whose 
name  you  specify. 

2.4.4  Specifying  the  Named  Data:  The  NAME  Command 

NAME  places  you  in  the  named  data  assignment  phase.  The  Form  F^ditor 
displays  a  questionnaire  that  collects  names  and  data  to  be  associated  with 
those  names.  Named  data  is  typically  used  to  hold  information  about  a  form 


The  KMS  11  Form  Kditor  (FKD)    2-7 


in  the  form  description  but  outside  the  form  itself.  Named  data  is  not  dis- 
played with  a  form. 

2.4.5  Storing  the  Form  Description:  The  SAVE  Command 

SAVE  causes  the  Form  Editor  to  place  the  form  description  that  you  are 
working  on  in  the  output  file  and  return  you  to  the  FED)  or  system  prompt, 
depending  on  how  you  started  the  program. 

If  field  attributes  have  not  yet  been  assigned  to  all  fields  when  the  SAVE 
operation  is  performed,  the  Form  Editor  supplies  default  values  for  any  fields 
whose  attributes  have  been  left  unspecified;  a  default  name  of  all  blanks  is 
supplied  as  the  field  name. 

2.4.6  Canceiling  the  Session  Without  Saving  the  Form:  The  QUIT 
Command 

QUIT  returns  you  to  the  FED  >  or  system  prompt.  The  form  you  were  editing 
is  not  saved  in  the  output  file,  it  is  destroyed. 


2.5  Edit  Status  Display 


When  you  are  in  the  EDIT  phase,  the  bottom  line  (24)  of  the  screen  displays 
information  about  the  current  status  of  the  Form  Editor.  The  format  for  the 
line  is: 

fjrvSOR:     T-:T    NOTv    LIN        1     COL  I     MODES:     T     T     AO'.'     INS       SFLECT:     I   IN        1     TOL  1 

FLD    SCR  21  132  FLD    PO     O'.'S  C3  132 


The  second  line  (above)  indicates  the  alternative  choice  or  the  limitations  of  the  items 
in  the  display. 

The  fields  on  line  24  are  dirplayed  in  reverse  video. 


CURSOR     This  section  indicates  the  line  and  character  that  the  cursor  is  located 
on. 

TXT.FLD       The  cursor  character  is  either  a  text  (TXT)  character  or  a  field  (FLD) 
character. 

NOR, SCR       The  cursor  line  is  either  a  normal  screen  line  (NOR)  or  a  part  of  a  scrolled 
region  (SCR). 

LIN  1-23      The  line  number  at  which  the  cursor  is  located. 

COL  1   l.'V2    The  column  number  at  which  the  cursor  is  located. 

MODES       This  section  indicates  the  status  of  the  internal  mode  indicators  of  the 
editor. 

TXT, FLD       The  current  input  mode  is  either  text  or  field. 

ADi.'.BCh       The  current  move  mode  is  either  Advance  (AD'.')  or  Backup  (BCK). 
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INS, QMS       The  current  input  mode  is  either  Insert  (INS)  or  Overstrike  (OUS). 

SELECT      This  section  is  present  only  if  a  select  range  is  active.  Otherwise,  this 
portion  of  the  Une  is  hlank. 

LIN  1-23      The  hne  number  at  which  the  select  point  is  located. 

COL  1-132    The  column  number  at  which  the  select  point  is  located. 


2.6  Form  Editor  Operations  Reference 

This  section  describes  the  creation  of  the  form's  screen  image  during  the 
EDIT  phase  and  the  assignment  of  all  attributes  during  the  FORM.  EDIT. 
ASSIGN,  and  NAME  phases. 

2.6.1  Creating  the  Form's  Screen  image 

The  Form  Editor  includes  a  text  editor  for  creating  and  modifying  screen 
images.  The  text  editor  lets  you  use  standard  operations  for  mode  changing, 
cursor  control,  and  text  modification. 

The  Form  Editor  lets  you  define  fields  in  the  form  for  data  input/output 
between  your  application  task  and  the  terminal  operator.  It  also  enables  you 
to  assign  video  attributes  (such  as  bold,  blink,  and  underline)  to  any  character 
or  set  of  characters  on  the  terminal  screen,  and  to  define  a  block  of  lines  as  a 
scrolled  area. 

NOTE 

The  Form  Editor  requires  a  VTIOO  term-nal  to  run  on;  however, 
neither  FED  nor  FDV  supports  the  VTlOO's  double-high  or 
double-wide  video  attributes. 


2.6.2  The  Text  Editor 

The  keyboard  performs  like  a  typewriter  when  you  use  the  Form  Editor:  it  lets 
you  input  and  delete  characters.  The  keypad  to  the  right  of  the  keyboard 
provides  operations  specifically  related  lo  the  Form  Editor.  It  is  recommended 
that  you  make  a  copy  of  the  keypad  layout  and  keep  it  at  the  terminal. 

The  text  editor  provides  four  kinds  of  operations: 

•  Mode-Changing  Operations 

You  change  modes  by  pressing  the  appropriate  key  or  key  combination  on 
the  keypad.  Modes  determine  placement  of  characters,  movement  forward 
or  backward  through  the  form,  and  definition  of  fields  and  background  text. 

•  Cursor  Control  Operations 

These  operations  change  the  cursor  position  but  do  not  affect  the  text.  The 
cursor  may  advance  only  to  the  margin  boundaries. 
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•  Text  Modification  Operations 

These  operations  insert,  delete,  and  modify  text. 

•  Scroll  Operation 

This  operation  permits  tht?  definition  of  a  scrolled  line.  Together  with  iden- 
tical lines  that  immediately  follow  it,  the  line  becomes  a  scrolled  area. 


2.6.3  Mode-Changing  Operations 

The  Form  Editor  works  in  several  modes.  The  mode  choices  are 
TEXT/FIELD,  INSERT/OVERSTRIKE,  and  ADVANCE/BACKUP.  Only 
one  of  each  pair  can  be  active  at  one  time. 

The  TEXT/FIELD  modes  tell  the  Form  Editor  whether  the  characters  you 
enter  are  background  text  characters  for  the  form  (TEXT  mode),  or  the  spe- 
cial set  of  field  characters  that  define  the  picture  format  of  a  field  (FIELD 
mode).  The  special  set  of  field  characters  includes  field-markers  (such  as 
slashes  and  hyphens  that  delimit  fields)  and  picture-validation  characters. 

The  INSERT/OVERSTRIKE  modes  determine  how  the  Form  Editor  places 
characters  in  the  form  with  respect  to  characters  already  there. 

The  ADVANCE/BACKUP  modes  determine  whether  the  Form  Editor  exe- 
cutes an  operation  in  a  forward  (right  and  downward)  or  backward  (left  and 
upward)  direction. 

2.6.3.1  TEXT/FIELD  —  TEXT  mode  is  activated  by  pressing  the  TEXT  key  on 
the  keypad.  Start  FIELD  mode  by  pressing  the  GOLD/FIELD  key  sequence. 
In  TEXT  mode,  the  Form  Editor  accepts  any  character  as  input.  It  enters  any 
printable  character  or  space  in  the  background  text  of  the  form.  The  Form 
Driver  does  not  see  these  characters  as  data.  Rather,  it  treats  the  characters  as 
constant  text  that  is  always  displayed  on  the  form.  TEXT  mode  is  deac- 
tivated by  pressing  the  GOLD/AFIELD  key  sequence,  which  places  you  in 
FIELD  mode. 

In  FIELD  mode,  the  Form  Editor  accepts  as  input  only  the  picture-validation 
characters  A,  C,  N,  X,  and  the  digit  9,  as  well  as  a  set  of  ASCII  field-marker 
characters.  Picture-validation  characters  tell  the  Form  Editor  whether  to  ac- 
cept alphabetic  (A),  alphanumeric  (C),  numeric  (9),  signed  numeric  (N),  or 
any  characters  (X)  as  input  for  each  character  position  in  a  field.  Field- 
marker  characters,  such  as  the  pound  sign  {^)  and  the  dash  (-),  are  text 
characters  that  you  may  define  as  part  of  a  field. 

If,  while  in  FIELD  mode,  you  enter  a  character  that  is  neither  a  field-marker 
nor  a  picture-validation  character,  the  Form  Editor  s  unds  the  terminal  bell 
and  rejects  the  input.  The  Form  Editor  accepts  a  blank  as  input  in  FIELD 
mode,  but  does  not  make  it  part  of  the  field.  Field-marker  and  picture-valida- 
tion characters  are  treated  as  such  only  when  the  Form  Editor  is  explicitly  in 
FIELD  mode.  For  example,  the  digit  9  is  associated  with  a  field  as  a  picture- 
validation  character  if  it  is  typed  in  FIELD  mode;  otherwise,  it  is  treated  ns  a 
text  character. 
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You  can  deactivate  FIELD  mode  and  return  to  TEXT  mode  by  pressing  the 
TEXT  key. 

2.6.3.2  ADVANCE/BACKUP  —  The  ADVANCE/BACKUP  modes  affect  the 
BLINE  (beginning  of  line)  and  EOL  (end  of  Hne)  operations.  They  do  not 
affect  character  insertion  or  deletion. 

ADVANCE  mode  causes  the  Form  Editor  to  implement  operations  in  the 
direction  moving  from  the  current  cursor  position  toward  the  end  of  the  line  or 
form.  You  can  deactivate  ADVANCE  mode  by  pressing  the  BACKUP  key. 

BACKUP  mode  causes  the  Form  Editor  to  implement  operations  in  the  direc- 
tion toward  the  beginning  of  the  line  or  form.  You  can  deactivate  BACKUP 
mode  by  pressing  the  ADVANCE  key. 

2.6.3.3  INSERT/OVERSTRIKE  —  The  INSERT/0 VERSTRIKE  modes  affect 
the  way  characters  are  placed  or  moved  when  you  type  or  make  deletions. 

INSERT  mode  places  typed  characters  at  the  current  cursor  location  and 
moves  the  cursor  to  the  right.  Any  other  characters  on  the  line  are  moved  over 
to  make  room  for  the  inserted  character.  If  characters  would  be  lost  by  being 
pushed  beyond  the  margin,  the  Form  Editor  sounds  the  terminal  bell  and 
rejects  the  insertion. 

If  you  delete  a  character  in  INSERT  mode,  the  Form  Editor  removes  the 
character  to  the  left  of  the  cursor  and  characters  to  the  right  slide  over  to  close 
the  space. 

You  can  deactivate  INSERT  mode  by  pressing  the  GOLD/OVERSTRIKE  key 
sequence. 

OVERSTRIKE  mode  causes  the  Form  Editor  to  replace  the  character  at  the 
current  cursor  position  with  the  new  character  typed  at  the  terminal.  When  a 
character  is  deleted,  adjacent  characters  do  not  close  up  the  line.  The  char- 
acter is  erased.  The  deleted  character  is  replaced  by  a  blank,  and  the  cursor  is 
positioned  on  that  character's  space.  You  can  enter  OVERSTRIKE  mode  by 
typing  the  GOLD/OVERSTRIKE  key  sequence. 

Deactivate  OVERSTRIKE  mode  by  pressing  the  INSERT  key. 

2.6.4  Cursor  Control  Operations 

The  following  operations  change  the  cursor's  position  during  an  editing  ses- 
sion. 

The  cursor  symbol  (either  a  solid  rectangle  or  an  underline)  blinks  on  the 
character  cursor  location.  A  row-column  counter  in  the  lower  right  corner  of 
the  screen  displays  the  precise  character  position  where  the  cursor  symbol  is 
blinking. 


U  par  row  (*) 


Press  the  UPARROW  key  to  nu)ve  \hv  cursor  up  one  line. 
You  cannot  move  the  cursor  above  the  top  margin  of  the 
torm,  otherwise  the  Form  Editor  sounds  the  terminal  bell. 
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Downarrow  (i) 


Right  arrow  ( 


Lett  arrow 


BLINE 


KK'I'IHN 


KOL 


RO'I'I'OM 


Press  the  DOWNARROW  key  to  move  the  cursor  down 
one  Hne.  You  cannot  move  the  cursor  below  the  bottom 
margin  of  the  form,  otherwise  the  Form  Editor  sounds  the 
terminal  bell. 

Press  the  lilOHTARROW  key  to  move  the  cursor  one 
character  position  to  the  right.  You  cannot  move  the  cur- 
sor beyond  the  right  margin,  otherwise  the  Form  Editor 
sounds  the  terminal  bell. 

Press  the  LEFTARROW  key  to  move  the  cursor  one  char- 
acter position  to  the  left.  You  cannot  move  the  cursor  be- 
yond the  left  margin,  otherwise  the  Form  F^ditor  sounds 
the  terminal  bell. 

Press  the  BLINE  key  to  move  the  cursor  to  the  beginning 
of  a  line.  Which  line  the  cursor  moves  to  the  beginning  of 
depends  on  whether  the  Form  Editor  is  in  ADVANCE  or 
BACKl'P  mode  when  the  BLINE  key  is  pressed. 

If  the  Form  Editor  is  in  ADVANCE  mode,  BLINE  moves 
the  cursor  to  the  beginning  of  the  next  line.  Pressing 
BLINE  again  moves  the  cursor  to  the  beginning  of  the 
subsequent  line. 

It  the  Form  Editor  is  in  BACKl'P  mode,  BLINE  moves 
the  cursor  to  the  beginning  of  the  current  line.  Pressing 
BLINE  again  moves  the  cursor  to  the  beginning  of  the 
previous  line. 

If  an  attempt  is  made  to  move  to  a  line  beyond  the  top  or 
bottom  screen  boundary,  the  Form  Editor  sounds  the  ter- 
minal bell. 

The  RETIRN  key  on  the  keyboard  provides  an  alternative 
to  LINE  when  used  in  ADVANCE  mode.  Pressing  RE- 
Tl'RN  moves  the  cursor  to  the  beginning  of  the  next  line. 
B.ACKl'P  mode  has  no  etfect  on  this  operation. 

Pressing  the  EOL  key  moves  the  cursor  to  the  end  of  a  line. 
Which  line  the  cursor  moves  to  the  end  of  depends  on 
whether  the  Form  Editor  is  in  ADVANCE  or  BACKl'P 
mode. 

If  the  Form  Editor  is  in  ADVANCE  mode.  EOL  moves  the 
cursor  to  the  end  of  the  current  line.  It  you  strike  EOL 
again,  the  cursor  moves  t(»  the  end  of  the  next  line. 

I!  the  Form  Editor  is  in  BACKl'P  mode.  EOL  moves  the 
cursor  to  the  end  ot  the  previous  line. 

IVessin,"  the  CiOLD/BOl  TOM  key  sequence  on  the  key- 
pad moves  the  cursor  to  the  bottom  right  corner  ol  the 
screen. 
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rop 

REPEAT 


Pressing  the  OOLD/TOP  key  sequence  on  the  keypad 
moves  the  cursor  to  the  top  lel't  corner  of  the  screen. 

It  you  press  the  (lOLD  key,  a  number,  and  an  operation 
that  you  want  to  perform,  the  Form  Editor  repeats  that 
operation  the  number  ot  times  that  you  have  specified. 
After  you  type  the  first  dijjit  of  the  number,  you  see  the 
prompt  REPEAT:  on  the  screen  as  well  as  the  number 
itself.  The  first  command  or  key  typed  after  the  dij^its  is 
repeated  that  number  of  times.  You  can  edit  the  number 
using  the  DELETE  key  to  increase  or  decrease  the  repeti- 
tions. 


2.6.5  Text  Modification  Operations 

Text  modification  operations  allow  you  to  insert,  modify,  and  delete  charac- 
ters and  lines  in  the  form,  as  well  as  to  assign  video  attributes  to  background 
text  and  fields. 

2.6.5.1  Inserting  ASCII  Characters  —  When  you  type  any  ASCII  character, 
the  Form  F^ditor  inserts  that  character  at  the  current  cursor  location  and 
moves  the  cursor  one  location  to  the  right. 

If  you  type  a  character  at  the  end  of  a  line,  the  Form  Editi)r  inserts  the 
character  in  the  last  available  position,  sounds  the  terminal  bell,  and  causes 
the  cursor  to  "bounce  back,"  leaving  the  cursor  symbol  at  the  last  character 
position  on  the  line. 

The  Form  Editor  handles  typed  characters  differently  depending  on  whether 
INSERT  or  OVERSTRIKE  mode  is  in  effect. 

2.6.5.2  Inserting  Characters  in  INSERT  Mode  —  In  INSERT  mode,  the  Form 
p]ditor  inserts  the  character  at  the  current  cursor  |)osition.  The  character 
previously  located  there  moves  one  position  to  the  right.  All  other  characters 
on  the  line  to  the  right  of  the  cursor  move  one  position  to  the  right.  If  the  last 
character  on  the  line  is  not  a  blank,  the  Form  Editor  rejects  any  operation 
that  would  cause  that  character  to  be  lost  by  pushing  it  off  the  end  ol  the  line. 
If  any  fields  are  moved  on  a  line,  the  Form  Editor  automatically  updates  their 
field  descriptors  in  the  form  description  to  reflect  the  change  in  the  field's 
screen  location. 

Press  the  DELETE  or  ®  key  on  the  keyboard  to  delete  the  character  to  the 
left  of  the  cursor.  If  the  cursor  position  is  column  1  when  this  key  is  pressed, 
the  Form  Editor  rejects  the  operation  and  sounds  the  terminal  bell. 

If  the  Form  Editor  is  in  INSERT  mode,  DELETE  moves  the  cursor  and  the 
remaining  characters  on  the  line  one  character  position  tn  the  left.  A  l)lank  is 
inserted  at  the  end  of  the  line. 

2.6.5.3  Inserting  Characters  in  the  OVERSTRIKE  Mode  —  In  OVERS  IRIKE 
mode,  the  Form  Editor  re|)laces  the  character  at  the  current  cursor  position 
with  the  new  character  that  is  ty|)ed. 


Ilu'  KMS   11  iM.rm  Kditor  (KKD)    2  l.'J 


Press  the  DELETE  or  (Ba)  key  on  the  keyboard  to  delete  the  character  to  the 
left  of  the  cursor.  If  the  cursor  position  is  column  1  when  this  key  is  pressed, 
the  Form  Editor  rejects  the  operation  and  sounds  the  terminal  bell. 

If  the  Form  Editor  is  in  INSERT  mode,  DELETE  moves  the  cursor  and  the 
remaining  characters  on  the  line  one  character  position  to  the  left.  A  blank  is 
inserted  at  the  end  of  the  line. 

If  the  Form  Editor  is  in  OVERSTRIKE  mode,  DELETE  replaces  the  char- 
acter to  the  left  of  the  cursor  with  a  blank  and  mvoves  the  cursor  one  position 
to  the  left.  If  a  field's  position  is  changed,  the  corresponding  descriptor  is 
updated.  However,  if  a  field's  picture  is  modified,  it  is  a  new  field  and  old 
attributes  are  lost. 


2.6.5.4  DELETE  CHARACTER  —  Press  the  DEL(ete)CHAR(acter)  key  on  the 
keypad  to  delete  the  character  at  the  current  cursor  position.  If  a  field's 
position  is  changed,  the  descriptor  is  updated.  However,  if  a  field's  picture  is 
changed,  it  is,  for  all  intents,  a  new  field  and  the  old  attributes  are  lost. 

If  the  Form  Editor  is  in  INSERT  mode,  DELCHAR  deletes  the  character, 
moves  the  remaining  characters  on  the  line  one  position  to  the  left  ,  and 
i.iserts  a  blank  at  the  end  of  the  line.  The  cursor  remains  in  its  current 
position. 

If  the  Form  Editor  is  in  OVERSTRIKE  mode,  DELCHAR  replaces  the  char- 
acter on  which  the  cursor  is  positioned  with  a  blank  and  moves  the  cursor  one 
position  to  the  right.  This  is  equivalent  to  typing  a  blank  while  in  0\  KR- 
STRIKE  mode.  If  the  cursor  is  on  the  last  character  position  on  the  line,  the 
Form  F^ditor  deletes  the  character,  sounds  the  terminal  bell,  and  leaves  the 
cursor  in  its  current  positicm.  The  Form  Edit  or  updates  the  field  descriptors 
of  fields  affected  by  the  change. 

2.6.5.5  OPENLINE  —  Press  the  OPENLINE  key  to  insert  a  blank  line  at  the 
current  line  and  move  all  remaining  lines  down  one  line.  The  Form  Editor 
reassigns  screen  locations  to  affected  fields  on  the  form  that  already  have  field 
descriptors.  If  the  next  to  last  line  on  the  screen  (the  last  line  available  for 
your  form)  is  not  blank,  the  Form  Editor  rejects  the  OPENLINE  operation, 
sounds  the  terminal  bell,  and  prints  an  error  message. 


2.6.5.6  (cm^  —  Press  the  ^mTvi  combination  to  redisplay  the  current  screen, 
and  restore  the  keypad  to  application  mode.  This  command  is  useful  when 
there  are  power  i'ailures.  static  problems,  or  distortions. 


2.6.5.7  ffRig  ~  Press  the  ^trTD)  combination  to  delete  all  characters  between 
the  current  cursor  position  and  the  beginning  ot  the  line.  The  curst)r  remains 
at  its  current  position, 

2.6.5.8  DELEOL  —  Press  the  DELEOL  (I)ELete  End  Of  Line)  key  on  the 
keypad  to  delete  all  characters  between  the  cursor  location  and  the  end  of  the 
line,  replacing  them  with  blanks.  The  cursor  remains  at  its  current  position. 
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2.6.5.9  DELLINE  —  Press  the  DEL(ete)  LINE  key  to  delete  the  current  line, 
move  all  the  lines  below  it  up  one  line,  and  insert  a  blank  line  at  the  bottom. 
The  Form  P^ditor  updates  the  field  descriptors  ol  any  affected  fields.  The 
I'NDELLINE  operation  allows  you  to  recover  the  deleted  line.  The  entire  line 
is  deleted  regardless  of  the  cursor  position  in  the  line. 


2.6.5.10  UKIELLINE  —  Press  the  UNDEL(ete)  LINE  key  to  restore  the  line 
or  line  segment  that  you  have  just  deleted.  This  operation  saves  you  from 
mistaken  or  accidental  deletions.  It  also  provides  you  with  an  easy  way  to 
duplicate  lines.  P^)r  example.  I'NDEI  LINF^  can  be  used  to  create  many  iden- 
tical lines  in  a  scrolled  area. 

The  effect  of  the  I'NDELLINF^  operation  depends  on  how  the  original  dele- 
tion v\as  performed. 

If  the  deletion  was  performed  by  using  a  I)F]LFX)L  or  a  £trl  u] .  the  Form  Editor 
places  th  e  contents  of  the  buffer  containing  the  deleted  characters  at  a  posi- 
tion starting  at  the  current  cursor  location.  If  deleted  by  ^HljJ-.  the  characters 
are  placed  to  the  left  (»f  the  cursor  location;  if  by  DELF.OL.  they  are  placed  to 
the  right  of  the  cursor  location.  This  restoration  can  be  performed  only  if  the 
deleted  characters  will  be  replacing  blanks.  Field  descriptors  for  the  original 
fields  are  restored  only  if  the  cursor  remains  at  the  location  where  the  original 
deletion  was  made. 

If  you  made  the  deletion  with  DELLINE.  the  Form  Editor  performs  an 
OPENLINE  operation  at  the  current  cursor  position.  It  then  places  the  de- 
leted line  on  the  screen  in  the  blank  line  created  by  OPENLINE.  The  P'orm 
Editor  updates  all  old  field  descriptors  for  fields  affected  by  the  OPENLINE 
operation  when  the  field's  position  changes,  but  not  the  picture.  The  field 
descriptors  for  the  deleted  line  are  restored  only  when  I'NDF^LLINE  is  per- 
formed the  first  time  and  on  the  same  line  where  the  deletion  was  done. 


2.6.5.11  REPEAT  —  If  you  press  the  OOLI)  key.  type  a  number,  and  perform 
an  operation  that  you  want  to  perform,  the  Form  Editor  repeats  that  opera- 
tion the  number  of  times  that  you  have  specified.  After  you  type  the  first  digit 
of  the  number,  the  prompt  REPEAT:  and  the  number  appear  on  the  screen. 
The  first  command  or  key  typed  after  the  digits  i.^  repealefl  that  number  of 
times,  ^"ou  can  edit  the  number  to  increase  or  deirease  the  repetitions  by 
using  the  del,  and  ctrlu.  operations,  del   i.s  not  a  repeatable  function. 

2.6.5.12  SELECT  —  Press  the  SELECT  key  to  mark  the  current  cursor  posi- 
tion as  a  reference  point  tor  video  attribute  assignment  and  ('IT  operations. 
SELECT  defines  the  first  character  (»f  the  select  range.  The  end  of  the  select 
ran  e  is  the  final  position  to  which  you  move  the  cursor.  In  other  wor(l>.  the 
selei  (  range  is  defined  as  all  character  positions  in  the  area  delimited  b\  the 
SELECT  position  at  one  corner  and  the  current  cursor  position  at  the  other. 
SELEC'''  =s  used  with  the  CIT.  PASTE  and  VIDEO  operations. 

2.6.5.13  CUT  —  Pressing  the  (TT  key  saves  all  the  characters  contained  in 
the  current  select  range  (the  area  defined  by  the  place  where  SELECT  was 
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pressed  and  the  current  cursor  position).  The  sharacters  are  stored  in  a  butler, 
and  blanks  replace  the  contents  of  the  area  in  the  screen  iniajie.  Il  a  SKLKCT 
operation  has  not  l)een  performed,  the  Form  Fxlitor  sounds  the  terminal  bell 
in  response  to  an  attempted  CUT. 


2.6.5.14  PASTE  —  The  PASTE  operation  inserts  the  characters  sa\ed  1)\ 
Cl'T  into  the  same  area  relative  to  the  current  location  ot  the  cursor  as 
obtained  when  the  orij^nnal  CI"!"  operation  occurred.  The  I'ASTK  ojjcration 
checks  that  the  inserted  material  docs  not  I'ross  boundary  lines  or  an\-  oilier 
text  or  fields  in  the  iorm.  If  boundar\  lines  are  crossed,  the  Form  F  iitoi' 
displays  the  error  messaj^e  "■('annol  paste  (>\t'r  maiiiins  or  non-blanks  oi'  in 
scrolled  areas"  and  sour.ds  the  terminal  bell. 

The  PASTE  operation  is  allowed  only  it  the  target  paste  area  tonsists  entirely 
oi  blanks.  If  tht  target  paste  area  is  not  lilank,  the  target  area  is  painted  in 
reverse  video,  and  a  message  is  displayed  on  line  24.  When  this  oi'curs.  press 
any  key  to  remove  the  reverse  video  attribute,  move  the  cursor  to  deline  a 
proper  target  area,  and  continue  the  operation. 


2.6.5.15  VIDEO  —  Press  the  VIDEO  key  to  aiiivate  video  attribute  assign- 
ment. The  prompt  '.'I  DEO  :  appears  on  the  terminal  screen.  r\pe  an\  of  tlie 
following  responses  to  activate  the  specified  attribute  within  the  select  range. 
I^ress  the  ENl'EH  key  after  typing  the  response.  The  abbreviations  iwv  under- 
lined: 

Bold       Displays  all  characters  within  the  select  range  in  bold  face. 

Blink       Displays  all  charaiiers  within  the  select   range  in  alter- 
nately increasing  and  decreasing  sireen  brightness. 

Reverse  Displays  all  characters  within  the  select  range  on  a  rcNcrse 
screen  background,  it  the  screen  is  white-on-black,  charac- 
ters in  rever.-<i  video  appear  in  black-on-white;  if  the  scrciMi 
is  black-on-white,  the  characters  appear  in  whitc-on- 
black. 

Underline      rnderlities  all  characters  «vithin  the  selei  t  range. 

riear      Deactivates  or  clears  all  the  currently  activi'  video  alt  rib 
utps  in  thf  selc  '  ra.nge. 

Kdit      This  is  not  an  attribute,  but   returns  >ou  lo  the  normal 
screen  editing  mode. 

You  tnusl  use  the  SELECT  operation  (see  abo\el  to  del. "nil  the  characters 
affected.  '!  he  SELECT  range  includes  both  text  and  fields;  it  ma\  cut  a  field 
in  the  middle.  .\  field  cut  in  two  by  the  .SJsLECT  operation  beconu-s  two 
separate  fields  if  the  two  parts  of  the  field  receive  different  '       d  attributes. 

^'ou  can  assign  \ideo  attributes  in  either   TEX  T  or  FIE'     '  mode. 
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Since  you  can  use  the  CLEAR  attribute  to  cancel  the  other  video  attributes, 
you  can  easily  experiment  with  the  various  attributes  to  achieve  the  best 
effect.  When  you  have  the  combination  of  attributes  that  you  want  to  keep  in 
your  form,  end  the  video  attribute  assignment  session  by  typing  EDIT  or 
pressing  the  RETURN  key. 

Note  that  a  character  can  have  more  than  one  video  attribute.  For  example, 
the  character  can  appear  on  the  operator's  screen  as  both  bold  and  blinking. 
However,  all  characters  in  a  field  must  have  the  same  video  attributes. 


2.6.6  Scroll  Operation 

The  effect  of  defining  an  area  as  .scrolled  is  that  the  Form  Driver  can  scroll 
lines  up  and  down  in  response  to  subroutine  calls  from  your  program  (see 
Chapter  7). 

The  scrolled  arra  that  the  Form  Editor  and  Form  Driver  work  with  is  like  a 
"window"  into  a  collection  of  data  too  large  to  appear  on  the  screen  at  any  one 
time.  Your  task  must  store  and  manipulate  any  data  '.hat  scrolls  off  the 
screen.  The  Form  Driver  does  not  have  the  capacity  to  store  such  data. 

Scrolling,  in  effect,  allows  you  to  create  a  form  of  unlimited  length  that  can  be 
filled  in  by  an  operator  as  information  becomes  available.  An  inventory  clerk 
receiving  lists  of  needed  materials  continuously  during  the  day,  or  a  bank 
teller  recording  ongoing  transactions,  could  use  a  scrolled  area  in  a  form 
application. 

Pressing  the  (;OLD/SCROLL  key  sequence  tells  the  Form  Editor  to  define  the 
current  line  as  scrolled.  A  scrolled  area  is  a  minimum  of  two  lines. 

The  (;OLD/NORMAL  key  sequence  removes  the  scrolling  attribute  from  a 
line. 

Once  you  have  defined  a  line  as  scrolled,  you  can  extend  the  scroll  and  create 
a  scrolled  area  by  using  the  DELLINE  and  l^NDELLINE  operations.  Delete 
the  scrolled  line  and  then  "undelete"  or  restore  it  as  many  times  as  you  wish, 
hi  this  way.  you  can  be  sure  that  the  lines  of  the  scrolled  area  are  identical. 

The  (;OLD/S(^H()LL  key  sequence  only  defines  the  current  lint  ^  scrolled. 
The  succeeding  lines  that  are  identical  to  the  scrolled  line  are  processed  as 
part  of  the  scrolled  area.  The  lirst  line  that  differs  in  any  detail  from  the 
original  scrolled  line  causes  the  Form  Editor  to  terminate  the  scroUe  1  area. 

All  lines  in  a  scrolled  area  must  have  identical  fields.  A  scrolled  area  should 
not  contain  text  except  for  field-marker  characters.  Once  the  text  scrolls  off 
the  screen,  it  is  lost. 

The  Form  Editor,  during  its  field  attribute  assignment  phase,  asks  you  about 
the  fields  on  the  first  line  of  a  scrolled  area  .)nly.  Fields  on  subse(iuent  lines  of 
the  scroll  are  considered  to  have  the  same  attributes  as  the  fields  on  the  first 
line.  A  form  may  have  more  than  one  scrolled  area. 


• 
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2.6.7  Field  Pictures 

A  field  is  a  set  of  contiguous  field  characters  (picture- validation  or  field- 
marker  characters)  terminated  by  a  blank,  a  non-field  character,  an  end-of- 
line  delimiter,  or  a  change  in  video  attributes.  Picture-validation  attributes 
apply  only  to  characters  in  fields.  They  tell  the  Form  Driver  whether  the 
operator  may  input  a  number,  a  letter,  etc.,  in  response  to  a  given  field. 

The  Form  Editor  recognizes  the  five  picture-validation  characters  shown  in 
Table  2-2. 

Table  2-2:     FED  Picture- Validation  Characters 


^ 


Character 


Type 


C 
A 

9 
N 
X 


Alphanumeric 

Alphabetic 

Numeric 

Signed  Numeric 

Anv  Character 


2.6.7.1  For  Alphanumeric  Characters-C  —  The  C  in  any  .liaracter  position 
defines  what  is  valid  input  in  that  position.  The  C  character  is  a  character 
attribute,  rather  than  a  field  attribute  that  allows  the  operator  to  input  the 
digits  0  through  9,  the  letters  A  through  Z  (either  in  upper  or  lower  case) 
and/or  a  space.  Any  other  attempted  input  sounds  the  terminal  bell  and 
causes  an  error  message. 

2.6.7.2  For  Letters-A  —  The  A  in  a  character  attribute  position  indicates  to 
the  operator  to  input  the  letters  A  through  Z  (either  in  upper  or  lower  case) 
and  a  space. 

2.6.7.3  For  Unsigned  Numbers-S  —  The  9  in  a  character  attribute  position 
indicates  to  the  operator  to  input  only  the  digits  0  through  9. 

2.6.7.4  For  Signed  Numbers-N  —  The  N  in  a  character  attribute  position 
allows  the  operator  to  input  the  digits  0  through  9,  with  only  one  decimal 
point  and  with  only  one  plus  (  +  )  sign  or  one  minus  (-)  sign.  Their  positions 
within  the  field  are  not  checked  by  the  Form  Driver.  Any  other  input  is 
rejected. 

2.6.7.5  For  Any  Printable  Characters-X  —  The  X  in  a  character  attribute 
position  allows  the  operator  to  input  any  displayable  character. 


2.6.7.6  For  Mixed  Pictures  —  A  single  field  may  contain  different  picture- 
validation  characters.  For  example,  a  field  constructed  to  accept  both  alpha- 
betic and  numeric  characters  specifically  may  look  like  this: 


AAAE)99 
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Such  a  field  allows  the  operator  to  enter  alphabetic  characters  in  the  first 
three  field  character  positions  and  digits  in  the  last  three  field  character 
positions.  The  field  is  said  to  have  a  "mixed  picture." 


2.6.7.7   With  Field-Marker  Characters 

looks  like  this 


For  example,  a  field  whose  picture 


999«AA-99 

contains  two  field-marker  characters,  the  pound  sign  and  the  dash. 

The  Form  Editor  treats  all  field-marker  characters  —  whether  leading,  trail- 
ing, or  embedded  — -  as  part  of  the  field  in  which  they  occur. 

A  field  that  contains  field-marker  characters  but  only  one  picture-validation 
character  does  not  have  a  mixed  picture.  Two  or  more  picture-validation 
characters  in  a  single  field  constitute  a  mixed  picture. 

A  field  may  contain  the  ASCII  characters  from  41  to  57  octal  and  72  to  100 
octal  as  field-marker  characters  (Table  2-3).  The  Form  Editor  accepts  field- 
marker  characters  when  in  FIELD  mode.  The  Form  Driver  does  not  return 
field-marker  characters  to  the  calling  task  or  include  them  in  the  length  of  the 
field.  Field-marker  characters  are  transparent  to  the  task,  which  does  not  pass 
them  to  the  Form  Driver  in  the  data  to  be  displayed  in  a  field. 

Table  2-3:    FED  Field-Marker  Characters 


Character 


Character 


& 


> 

(a 


2.6.8  Assigning  Form-Wide  Attributes 

The  Form  Editor  collects  form-wide  attributes  by  displaying  the  question- 
naire shown  in  Figure  2-2.  The  Form  Editor  automatically  displays  the  Form 
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Wide  Attributes  questionnaire  when  you  create  a  new  form  or  when  you  type 
FORM  in  response  to  the  COMMAND  :  prompt.  The  questionnaire  contains  the 
default  conditions  for  each  choice. 


Figure  2-2:     Form-Wide  Attributes  Questionnaire 


Form  Name 
Help  Form  N  a  (ti  e 
Re'ierse  Screen 
C  I.I  r  r  e  1"!  t  S  c  r  e  e  I'l 
Wide  S  c  r  e  e  ri 
5  t  a  r  t  1  ri  3  Line 
E  ii  d  1  ri  g  L  1  n  e 

Impure  Area 
Form  Size 


(  'i' 


I  1 


N>  N 

N)  N 

N)  N 

23  I  1 


'  1  ,23) 


b  V  t  e  5 
w  0  r  d  s 


Press  the  TAB  key  to  move  from  one  question  to  the  next.  When  you  have 
completed  the  necessary  input  and  want  to  exit,  return  to  the  COMMAND: 
prompt  by  pressing  the  ENTER  key. 

The  fields  listed  in  the  Form-Wide  Attributes  Questionnaire  are: 


2.6.8.1  Form  Name  —  A  response  to  this  field  is  required.  The  name  of  the 
form  is  used  in  the  form  library  directory  and  by  Form  Driver  calls. 

A  form  is  always  saved  in  a  file  with  the  name:  form. FRM.  When  inserted  in  a 
library,  the  name  of  the  form  is  always  taken  from  the  form  itself.  The  form 
name  mav  not  contain  embedded  blanks. 


2.6.8.2  Help  Form  Name  —  This  field  contains  the  name  of  an  associated 
Help  form.  The  field  may  be  left  blank. 

2.6.8.3  Reverse  Screen  —  If  this  field  contains  a  Y,  the  form  is  displayed 
black-on-white.  If  it  contains  an  N,  the  display  is  white-on-black.  The  default 

is  N. 

2.6.8.4  Current  Screen  —  If  this  field  contains  a  Y.  the  Form  Driver  displays 
the  form  in  the  current  screen  mode.  An  80-column  form  with  a  Y  answer  to 
this  field  does  not  require  a  change  if  the  current  mode  is  set  at  132  columns. 

The  current  screen  also  applies  to  reverse  screen.  If  current  screen  is  soecified. 
the  Form  Driver  does  not  change  the  screen  background  or  the  screen  width, 
unless  the  form  is  specified  for  132  columns  and  the  screen  is  currently  80 
columns. 

You  cannot  specify  Y  both  to  this  option  and  to  the  wide  screen  option  de- 
scribed below.  If  the  choice  is  N,  the  Form  Driver  resets  the  screen  if  necessary 
to  conform  to  the  display  mode  for  this  form.  The  default  value  is  N. 


2.6.8.5   Wide  Screen  —  If  this  field  contains  a  Y,  the  form  is  displayed  in  132- 
column  mode  and  the  Current  Screen  option  described  above  is  set  to  N.  If  the 
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field  contains  an  N.  the  form  is  displayed  in  8()-column  mode.  The  F^orm 
P'ditor  changes  the  terminal  to  the  selected  mode.  The  default  is  N. 

2.6.8.6  Starting  Line  —  This  field  contains  a  value  from  1  to  2:^  inclusive, 
indicating  the  first  hnt  of  the  screen  to  be  cleared  when  the  form  is  displayed. 
If  you  specify  a  starting  line  number  greater  than  the  ending  line  number,  the 
Form  Kditor  automatically  replaces  your  entry  with  the  default  value  of  1. 

2.6.8.7  Ending  Line  —  This  field  contains  a  value  from  1  to  23  inclusive, 
indicating  the  last  line  of  the  screen  to  be  cleared  when  the  form  is  displayed. 
If  the  supplied  value  is  less  than  the  starting  line  number,  the  default  value  of 
23  is  used. 

Starting  and  ending  line  number  defines  the  area  of  the  screen  to  be  cleared 
when  the  form  is  displayed  using  the  FSHOW  call  (which  doesn't  automati- 
cally clear  the  entire  screen)  oi  when  the  form  is  displayed  as  a  help  form. 

2.6.8.8  Impure  Area  —  This  is  a  Display-Only  field  that  indicates  the  size  of 
the  impure  area  required  when  the  form  is  displayed  by  the  Form  Driver.  For 
applications  written  in  a  high  level  language,  the  impure  area  provided  must 
be  64  bytes  larger  than  specified  by  FED.  When  creating  a  new  forni,  this  field 
is  initially  displayed  as  question  marks. 

2.6.8.9  Form  Size  —  This  is  a  Display-Only  field  thai  indicates  the  length  of 
the  form.  This  value  is  used  in  calculating  the  media  or  memory  storage 
requirements  for  the  form.  When  creating  a  new  form,  the  field  is  initially 
displayed  as  question  marks  until  the  Form  Editor  determines  the  correct 
value. 


2.6.9  Assign  ng  Field  Attributes 

The  Form  Editor  collects  field  attributes  by  displaying  the  questionnaire 
shown  in  Figure  2-3.  Each  entry  in  the  questionnaire  designates  a  single 
attribute  for  a  field.  If  the  form  or  field  is  a  new  one,  the  Form  Editor  supplies 
default  values  in  the  questionnaire.  If  the  attributes  for  the  field  were  assigned 
in  a  previous  editing  session,  those  values  are  dis{)layed. 


Figure  2  3:     Field  Attributes  Questionnaire 

Name      :       R  i  3  h  i  Just  (  'i'  .  N  )  N  Clear  Char  (  c  h  r  ;   Zero  Fill  (Y.N)  N 

D  e  f  a  ..1 1  t  : 

Help     : 

Auto     Tab     (V.N)     N    R  e  5  p    TV  e «» d     (Y.N)     N    M  m  s  I    Fill     <  Y  .  N )     N    Fixed    Dec     (Y.N)     N 

Indexed     (N.H.M)     N    Disp    Only     iV.N)     N    Echo    Off     (V.N)     N    Supu    Oiilv      (V.M)     N 

Enter  the  attribute  assignment   phase  by  typing  ASSKiN  and  any  of  the 
following  options  in  response  to  the  COMMAND  :  prompt. 


ASSIGN  NEW 
ASSIGN  ALL 


A.ssign  attributes  only  to  new  fields 

Assign  or  edit  all  attributes  —  for  all  fields  in 
form 


The  KMS  11  Form  Editor  (FED)    2-21 


ASSIGN  FIELD  fldname       Assign  or  edit  attributes  for  the  field  named 

fldname 

ASSIGN  is  used  to  assign  field  attributes  after  creating  the  form's  screen 
image.  Any  new  fields  placed  in  the  form  may  have  their  field  attributes 
defined  by  using  either  ASSIGN  or  ASSIGN  NEW.  If  you  exit  from  the  field 
attribute  assignment  phase  and  then  return  to  change  any  previously  assigned 
fields,  you  must  use  the  ASSIGN  ALL  or  ASSIGN  FIELD  commands. 

Fields  that  have  changed  their  locations  as  a  result  of  the  OPENLINE  or 
DELLINE  operations,  or  as  a  result  of  character  insertion  or  deletion  on 
another  part  of  the  line,  are  recognized  as  existing  fields.  Fields  whose  pic- 
tures are  modified  must  be  redefined. 

If  you  select  ASSIGN  NEW  or  ASSIGN  ALL,  you  proceed  to  assign  attributes 
to  the  next  field  by  pressing  the  ENTER  key.  To  return  to  the  COMMAND: 
prompt  before  you  have  finished  all  the  fields,  type  the  period  (.)  on  the 
keypad.  (Remember  that  this  results  in  assignment  of  default  values  to  all 
remaining  fields  in  the  form.  The  default  value  for  a  field  name  is  6  blanks.)  If 
you  used  ASSIGN  FIELD,  the  Form  Editor  returns  to  the  COMMAND  :  prompt 
when  you  press  ENTER  for  that  field. 

The  Form  Editor  displays  the  field  attribute  questionnaire  for  each  field  on 
the  form.  The  TAB  key  moves  the  cursor  from  one  field  to  the  next  within  the 
questionnaire.  Pressing  ENTER  after  going  through  the  questionnaire  for  the 
last  field  in  a  form  causes  the  Form  Editor  to  reissue  the  COMMAND  :  prompt. 

NOTE 

The  assignment  of  invalid  combinations  of  attributes  to  a  field 
results  in  an  error  message.  To  continue,  you  press  the  ENTER 
key  to  redisplay  the  questionnaire  for  that  field  and  correct  the 
attribute  th   t  caused  the  error  message. 

The  following  field  attributes  appear  in  the  Field  Attributes  Questionnaire: 


Name 


Right  Just 


Clear  Char 


Contains  the  name  by  which  the  field  is  known  and  referred  to 
by  your  task.  I'uique  field  names  are  not  required  if  a  form  is  to 
be  accessed  by  the  FGETAL  call.  However,  if  the  application  is 
to  access  one  field  at  a  time,  unique  names  should  be  assigned. 
(If  a  form  contains  more  than  one  field  with  the  same  name,  the 
Form  Driver  can  access  only  the  first  one.)  The  default  value  for 
a  field  name  is  6  blanks. 

If  you  type  a  Y,  the  field  is  right-justified.  If  you  type  an  N.  the 
field  is  left -justified.  A  right-justified  field  may  not  contain  a 
mixed  picture.  The  default  is  N. 

The  character  that  you  type  in  this  field  is  displayed  in  place  of 
the  fill  (  iracter  (either  zero  or  blank  for  the  field).  For  zero- 
filled  field..,  it  must  be  a  zero.  For  blank  filled  fields,  the  clear 
character  may  be  any  character;  underline,  period,  and  blank 
are  the  most  common  choices.  A  blank  is  the  default. 
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Zero  Fill  If  you  type  a  Y.  the  field  is  filled  with  zeroes  before  the  operator 

enters  any  data  in  the  field.  Il  you  type  an  N.  l)lanks  are  stored 
in  the  field.  Note  that  the  Clear  Character  attribute  must  be  set 
to  zero  if  the  field  is  zero-filled.  The  default  is  N.  The  fill  char- 
aeter  is  also  returned  to  the  calling  program  in  any  positions  the 
terminal  operator  does  not  enter  data  in. 

Default  Specifies  the  initial  value  to  be  stored  in  the  tield  wiien  the  form 

is  loaded  by  the  Form  Driver.  II  you  do  not  respond,  the  field 
contains  either  blanks  or  zeroes,  depending  on  your  response  to 
the  Zero  Fill  attribute.  Your  answer  to  Default  shovdd  be  con 
sistent  with  the  picture-validation  type  of  the  tield.  ll  a  detault 
value  is  not  specified,  the  internal  representation  ol  the  field  is 
blank  or  zerofilled  depending  on  the  definition.  The  fill  v\mu- 
acier  is  always  displayed  as  the  clear  character.  If  a  field  h;is  no 
default  value  it  is  initially  displayed  with  clear  character^.  The 
default  value  mav  not  be  longer  than  the  lield. 


NOTK 

The  Form  Kditor  does  not  validate  default  data 
values  to  be  certain  that  they  are  legal  and  con- 
form to  the  picture-validation  type  of  the  lield. 


H 


eh) 


Auto  Tab 


iated  with  the  tield  that  the 


Specifies  a  line  of  information  assoc 
user  can  read  by  pressing  the  HKLP  key.  The  help  message 
appears  on  the  last  line  of  the  terminal  .screen.  The  di'lauli   i^ 
that  no  help  message  is  displayed,  if  this  field  is  lett  blank,  the 
Help  form  for  the  entire  form  is  displayed  il  there  is  one.  OtluM 
ise.  the  message  "NO  HKLP  A\A1L.\BLK""  is  displaved. 


w 


Determines  whether  entering  the  last  character  in  the  field 
causes  the  cursor  to  advam-(>  automatically  to  the  next  lield. 
Typing  a  ^'  specifies  that  Auto  Tab  is  in  effect .  The  (h'lault  is  .\. 


Resp  Reqd  At  least  one  character  that  isn't  the  fill  character  must  lie  en- 
tered in  the  field.  If  yovi  type  a  ^■,  the  operator  at  the  terminal 
must  respond  to  the  field  with  some  kind  of  input  betore  contin- 
uing. If  you  type  an  N.  the  operator  does  not  have  ♦«)  respond  to 
tlie  field.  The  Form  Dr.ver  uses  this  attril)Ute  to  validate  the 
operator's  responses  for  fields.  The  default  \alue  is  N. 


Must  Fill 


if  data  is  entered  in  the  field,  it  must  be  filled  so  that  it  does  not 
;ontain  a  single  fill  character.  The  field  must  be  either  einptv  or 
lull    The  default  value  is  \. 


A  field  defined  as  must-fill  but  not  response-reciuired  must  be 
filled  by  the  operator  onlv  if  he  or  she  emi'is  data  in  it  II  ina\  lie 
left  empty. 

Fixed  Dec       H  you  type  a  Y.  the  field  is  a  li.xed  decimal  field,  provided  thai 


the  picture  must  be  all    Ms  with  an  embedded    decimal  j) 


oinl 
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Signed  numeric  is  not  valid.  If  you  type  an  N  or  if  the  numeric 
picture-validation  type  is  not  in  effect,  the  field  is  not  fixed 
decimal.  The  default  value  is  N. 

Indexed  ""his  attribute  enables  you  to  define  identical  fields,  one  below 

the  other,  as  indexed  fields.  Typing  an  N  indicates  that  the  field 
is  not  indexed.  An  H  indicates  that  the  field  is  horizontally 
indexed  and  that  the  t  ursor  should  proceed  horizontally  to  the 
next  field  on  the  same  line  in  "esponsp  to  the  TAB  key  (or  Auto 
Tab)  if  the  next  field  is  aiso  horizontally  indexed.  Typing  a  V 
indicates  that  the  field  is  vertically  indexed  and  that  the  cursor 
should  proceed  vertically  to  the  next  field  in  the  same  column  in 
response  to  the  TAB  key  (or  Auto  Tab).  The  default  value  is  N. 
The  Indexed  attribute  is  illegal  for  fields  in  scrolled  areas. 

Disp  Only  If  you  type  a  Y,  only  your  application  program  may  place  data 
in  the  field.  If  you  type  an  N,  both  the  terminal  operator  and 
your  task  may  enter  data  in  the  field.  The  default  is  N. 

Echo  Off  If  you  type  a  Y,  data  in  the  field  isn't  displayed  on  the  terminal 
screen.  If  you  type  an  N.  the  characters  echo  as  in  normal  opera- 
tion. The  default  is  N. 

Supv  Only  If  you  type  a  Y,  the  field  is  display-only  unless  the  task  has 
turned  off  supervisor-only  mode  (by  means  of  a  Form  Driver 
call).  If  you  type  an  N,  the  field  is  not  display-only  and  may  be 
accessed  by  the  terminal  operator.  The  default  value  is  N. 

The  attribute  that  defines  a  field  as  .scrolled  does  not  appear  on  this  question- 
naire. You  can  define  all  fields  on  a  line  as  scrolled  fields  by  pressing  the 
(]OLD/SCROLL  key  sequence  during  the  EDIT  phase. 


2.6.10  Assigning  Named  Data  Attributes 

Named  data  is  any  data  that  is  to  be  associated  with  a  form  but  not  displayed 
with  it.  Usually,  named  data  contains  information  that  the  applicj':ion  uses  to 
control  task  flow  in  a  form-dependent  manner.  The  information  may  consist 
of  the  names  of  other  forms  or  task  modules.  Named  data  al.so  might  contain 
field  specific  data.  Your  task  accesses  named  data  by  means  of  calls  to  the 
F'orm  Driver. 

The  questionnaire  that  collects  named  data  consists  of  the  two  hori/ont ally- 
indexed  fields  of  16  elements.  When  the  questionnaire  appears,  it  includes  all 
existing  named  data  followed  by  blank  named  data  lields. 

Enter  the  named  data  phase  by  typing  NAME  in  response  to  the 
COMMAND:  prompt.  The  Form  Editor  displays  the  Named  Data  (juestion- 
naire.  When  the  questionnaire  appears  on  the  screen,  (he  cursor  is  at  the  first 
character  position  of  the  first  field,  Enter  the  name  by  which  you  want  to 
reference  the  data  that  you  supply  next.  Alter  you  enter  the  name,  press  the 
TAB  key  to  move  into  (he  data  field.  Now  enter  or  edit  the  named  data  itself. 
If  a  name  already  exists,  simply  tab  over  to  the  data  field.  Exit  from  the 
named  data  phase  by  pressing  the  EN  TEH  key. 
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The  fields  in  the  Named  Data  questionnaire  (Fifiure  2-4)  are: 

NAME  A  6-character  field  that  receives  the  name  of  the  data  item.  Form 
Driver  calls  access  a  particular  element  of  named  data  by  usinj? 
either  its  name  or  its  index  number  in  the  list  of  named  data  for  a 
form. 

DATA       A  60-character  field  that  receives  the  data. 


Figure  2-4:    Named  Data  Questionnaire 


Name 


Data 


2.7  A  Step-by-step  Example  of  How  to  Use  the  Form  Editor 

This  section  presents  an  example  of  creating  and  modifying  screen  versions  of 
forms.  The  example  demonstrates  some  of  the  most  common  Form  Kditor 
commands,  functions,  and  design  processes.  However,  the  example  does  not 
cover  all  Form  Editor  features,  and  it  is  not  a  complete  tutorial.  Instead,  the 
purposes  of  this  example  are  as  follows: 

•  To  illustrate  how  you  can  design  a  computerized  version  of  a  simple  printed 
form. 

•  To  show  you  what  the  screen  looks  like  while  you  are  working  with  the  Form 
Editor. 

•  To  introduce  how  the  Form  P'ditor  uses  the  VTIOO  special  function  keypad 
to  control  editing  functions. 

•  To  introduce  how  the  Form  Editor  uses  the  Form  Driver  and  special  ques- 
tionnaires that  collect  information  from  you  about  the  form  that  you  are 
designing. 
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This  example  has  three  major  stages.  In  the  first  stage,  a  printed  form  is 
described.  Assume  that  the  form  was  originally  designed  for  a  card  file  of  a 
company's  vendors.  Before  designing  the  computerized  version  of  the  form, 
read  the  requirements  of  the  fields  in  the  form  section  (2.7.1.2). 

In  the  second  stage,  you  create  the  screen  version  of  the  form.  Each  step  in 
this  stage  starts  with  an  instruction,  and  each  step  completes  a  part  of  the 
exercise  of  designing  the  computerized  version  of  the  sample  form.  Read  the 
instruction,  and  then  look  at  your  screen  while  you  follow  the  instruction. 
Watch  how  the  Form  Editor  responds.  Finally,  read  the  short  explanation 
that  follows  the  instruction. 

In  the  third  stage,  you  modify  one  of  the  demonstration  forms  that  you 
received  as  part  of  your  FMS  software  kit.  I'se  the  same  procedure  lor  the 
steps  in  this  stage  as  for  the  second  stage. 

You  are  encouraged  to  try  using  this  example.  You  will  be  able  to  add  the  new 
form  that  you  create  and  the  demonstration  form  that  you  modify  to  the 
demonstration  form  library  file  DEMLIB.FLB.  You  can  then  demonstrate 
how  your  new  form  works  by  running  one  of  the  demonstration  programs  that 
are  in  vour  FMS  s.itware  kit. 


2.7.1  The  Printed  Form 

The  first  steps  in  designing  a  screen  version  of  the  form  are: 

•  Provide  an  overview  or  a  rough  draft  of  the  new  form. 

•  Describe  the  requirements  for  each  field. 

•  Describe  the  layout  of  the  form  and  any  special  video  features  that  it  is  to 
include. 

•  Sketch  the  screen  form  and  include  the  maximum  lengths  of  fields. 


2.7.1.1  Overview  of  the  New  Form  —  The  new  form  will  have  fields  for  all  of 
the  information  that  the  printed  form  can  contain.  This  exam|)le  assumes 
that  the  new  form  will  be  used  only  to  enter  the  vendor  information  that  is 
currently  in  a  card  file. 

VENDOR  is  the  name  to  be  assigned  to  the  form.  For  now  the  form  will  not 
have  a  help  form  associated  with  it.  It  will  use  the  8()-column  screen  width  and 
the  full  screen  height  (screen  lines  1  through  2'.]). 

2.7.1.2  Requirements  of  the  Fieids  in  the  Original  Form  —  This  section  de- 
scribes all  of  the  requirements  for  the  fields  that  are  in  the  original  lorm. 

1.     Vendor  Number 

Vendor  numbers  are  in  the  following  lorm: 

B-GT-OOHf) 
The  first  character  can  be  any  letter.  Except  for  two  hyphens  as  shown. 
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the  remaining  characters  must  be  digits.  An  operator  must  enter  the 
vendor  number.  Programs  that  use  the  form  can  then  use  the  vendor 
number  to  get  other  vendor  information  from  a  computer  file  and  display 
that  information. 

2.  Vendor  Name 

Vendor  names  may  be  as  long  as  38  characters  and  may  include  any 
printable  character.  When  the  name  is  first  entered,  it  must  be  typed 
exactly  as  it  appears  on  the  file  card. 

3.  Address 

The  top  line  in  the  address  shows  the  vendor's  street  address.  The  next 
line  shows  the  city  and  state.  The  bottom  line  shows  foreign  countries  and 
mail  codes  such  as  the  ZIP  code. 

4.  Contact 

Contact  names  are  the  names  of  the  people  in  the  vendor  companies  who 
are  most  informed  about  the  sample  company's  business.  Contact  names 
may  be  as  long  as  28  characters  and  may  include  any  printable  character. 

5.  Phone 

The  form  needs  to  be  designed  only  for  one  standard  North  American 
telephone  number  in  the  following  form: 

(123)  555-4678 

As  shown,  parentheses  enclose  a  3-digit  area  code.  A  7-digit  number  has  a 
hyphen  separating  the  exchange  code  from  the  line  number.  All  input 
characters  must  be  numbers.  The  telephone  number  is  not  required  infor- 
mation, but  if  a  telephone  number  is  entered,  all  10  digits  must  be  en- 
tered. The  area  code  has  the  default  value  111  because  most  vendors  are  in 
that  area,  but  there  is  no  default  value  for  the  balance  of  the  telephone 
number. 

6.  Extension 

The  form  needs  to  be  designed  for  two  telephone  extension  numbers.  To 
make  the  new  form  as  flexible  as  the  original  printed  form,  the  new  tbrm 
will  accept  extension  numbers  up  to  seven  digits,  to  cover  the  cases  when 
different  vendor  extensions  are  complete  7-digit  telephone  numbers.  The 
telephone  extension  is  not  required  information.  All  input  characters  must 
be  numbers,  but  any  number  of  characters  is  valid. 


• 


2.7.1.3  Layout  and  Video  Features  of  the  New  Form  —  The  layout  of  the  new 
form  will  follow  the  sketch  that  appears  in  Figure  2  5.  With  a  screen  width  of 
80  columns,  there  is  ample  room.  Abbreviations  are  not  necessary.  The  ex- 
ample assumes  that  the  vendor  number  is  the  most  important  piece  of  vendor 
data,  and  therefore,  the  sketch  shows  it  at  the  upper-left  corner  of  the  form. 

The  field  will  be  in  reverse  video  and  underlined  to  shov,'  its  importance. 
Other  fields  will  have  the  bold  video  attribute  to  make  the  values  that  opera 
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tors  enter  more  visible.  The  title  of  the  form,  "Vendor  Data,"  will  also  have 
the  bold  video  attribute.  Field  labels  will  be  in  standard  video.  (The  bold 
video  attribute  really  doesn't  look  good  in  a  form  if  it's  used  as  much  as 
specified  here.) 

2.7.1.4  Sketch  of  the  Form  Named  VENDOR  —  Figure  2-5  is  a  sketch  of  the 
form  that  you  will  be  creating  in  this  example.  Several  other  designs  would  be 
equally  effective.  In  many  cases,  the  sketch  that  you  use  may  be  less  detailed 
than  the  one  in  Figure  2-5.  Since  you  can  easily  change  any  design  by  using 
the  Form  Editor,  you  need  only  enough  detail  in  a  sketch  to  show  the  number 
of  fields  on  each  line  and  the  rough  alignment  of  fields.  More  detail  appears  in 
Figure  2-5  in  order  to  increase  the  reliability  of  this  example. 


Figure  2-5:     Sketch  of  VENDOR 


^OiOTAcTt 


-\ 


2.7.2  Creating  the  Screen  Form 


This  section  guides  you  from  starting  the  Form  Editor  through  each  of  the 
other  steps  that  you  need  to  complete  in  order  to  create  a  screen  version  of  the 
form  named  VENDOR.  Each  step  starts  with  an  instruction.  Head  the  in- 
struction, and  then  look  at  your  screen  while  you  follow  the  instruction. 
Watch  how  the  Form  Editor  responds.  Finally,  if  an  explanation  follosvs  the 
instruction,  read  it  and  then  go  on  to  the  next  step.  Each  exi)lanation  begins 
with  the  symbol  >>>. 

The  first  time  you  work  with  this  example,  follow  each  instruction  carefully. 
Each  step  has  been  written  to  depend  closely  on  the  preceding  step. 

1.  Log  on  to  a  system  that  includes  the  Form  Editor.  Check  with  your  .system 
manager,  if  you  are  not  sure  whether  or  not  the  Form  P^litor  is  available 
on  vour  system. 


# 


• 
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2.    Set  your  VTIOO  as  follows: 

•  For  the  block  cursor  (S;). 
Use  SET-UP  MODE  B. 

•  For  the  80-column  screen  width. 

In  SET-UP  MODE  A  (This  is  the  default). 

•  For  the  standard  video  display  (light  characters  on  a  dark  background). 
Use  SET-UP  MODE  B  (This  is  the  default). 

•  For  signalling  with  the  terminal  bell. 
Use  SET  UP  MODE  B. 

(The  VT-WO  User  Guide  has  detailed  directions.) 


2.7.2.1    Starting  the  Form  Editor  -  Step  3  — 

3.  Start  the  Form  Editor  by  entering  the  appropriate  command  or  sequence 
of  commands  from  the  following  list.  The  prompts  that  your  system  types 
are  in  black.  The  responses  that  you  should  type  are  in  red. 

For  RSX-llM  and  UM-PLUS  systems  - 

MCR>RUN  $FED(iTj 
FED>''CR® 

For  IAS  systems  - 

MCR>FED  RET^ 
FED>/CR(RETj 

>>>  Each  set  of  commands  starts  the  Form  Editor  on  the  corresponding 
system.  The  commands  also  specify  thai  you  are  developing  a  screen  form. 
The  Form  Editor  responds  by  displaying  the  first  questionnaire  for  a  new 
screen  form,  the  Form-Wide  Attributes  questionnaire. 


2.7.2.2    Assigning  the  Form  Name  -  Steps  4  -  5  — 

4.  On  the  keyboard,  type  the  name  VENDOR.  If  you  make  a  mistake,  press 
the  DELETE  key  to  erase  incorrect  characters  and  then  complete  the  form 
name  correctly.  Later  steps  depend  on  the  fact  that  the  name  of  the  new 
form  is  VENDOR.  When  the  form  name  is  correct,  press  the  RETURN 
key. 

>>>  Each  character  you  type  appears  in  the  "Form  Name"  field.  The 
cursor  advances  through  the  field  from  left  to  right. 

When  a  questionnaire  is  displayed,  press  the  RETURN  key  to  do  the 
following: 

•  Assign  to  each  questionnaire  whatever  value  you  put  into  the  field. 

•  Store  the  questionnaire  information  internally  until  you  change  it  or 
save  the  form  description  that  you  are  creating. 

•  Erase  the  questionnaire  from  the  screen  and  respond  to  a  Form  Editor 
command,  in  some  cases. 
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•  Continue  a  process  by  changing  your  display  in  some  other  way. 

With  the  Form-Wide  Attributes  questionnaire  displayed,  the  RKTL'RN 
key  always  causes  the  Form  Editor  to  erase  the  screen  and  ask  you  tor  a 
F'orm  Editor  command  by  displaying  the  prompt  COMMAND:  <m  the  last 
line. 

5.  Type  the  command  EDIT.  Press  the  DELETE  key  to  correct  mistakes. 
VVhen  you  complete  the  command,  use  the  ENTER  function  -  press  the 
ENTER  key  on  the  keypad,  or  press  the  RETURN  key. 

-•^>  The  ENTER  or  RETimN  function  keys  cause  the  P^)rm  Editor  to 
execute  the  command  that  you  have  just  typed.  When  the  Form  Editor 
executes  the  EDIT  command,  it  displays  the  screen  form  that  you  are 
designing  and  shows  you  each  detail  of  the  form  that  you  have  specified  so 
far.  In  this  case,  your  new  form  is  entirely  blank  —  23  lines  long,  with  80 
spaces  in  each  line.  The  cursor  appears  in  the  upper  left  corner  of  the 
screen  on  Line  1  and  Column  1. 

While  you  are  editing  a  form,  the  Form  Editor  uses  Line  24  to  show  you 
information  about  the  cursor's  locaticm  and  several  Form  Editor  settings 
that  you  can  change  while  you  are  editing.  At  this  point,  the  different 
sections  of  Line  24  and  their  meanings  are: 

•  CURSOR  TXT  NOR  LIN    1   COL    1 

The  character  that  the  cursor  is  on  is  a  text  character  (TXT)  and  the  line 
is  a  normal  line  of  a  form  (NOR),  not  a  scrolled  line.  (Scrolling  features 
are  explained  later  in  this  chapter.)  The  cursor's  position  is  on  Line  1 
and  Column  1. 

•  MODES  TXT  OMS  ADV 

The  current  settings  of  the  editing  modes  are  as  follows  (later  steps 
demonstrate  the  effects  of  the  different  modes): 

—  The  text  mode  (TXT)  f»)r  entering  background  text.  You  cannot  use 
the  field  mode  until  you  have  put  in  all  the  background  text.  The 
field  mode  will  allow  you  to  assign  attributes  to  each  field  label  you 
created  in  text  mode. 

—  The  overstrike  mode  (OUS)  for  replacing  the  character  that  the  cur- 
sor is  on  with  the  character  that  you  type. 

—  The  advance  mode  (ADU)  for  advancing  the  cursor  to  the  right  and 
downward  when  certain  cursor  movement  functions  are  used. 


NOTE 

While  using  the  Form  Editor,  you  will  be  using  the  form  editor 
auxiliary  keypad  as  well  as  the  main  keyboard  to  perform  spe- 
cific form  editing  functions.  Refer  to  the  Form  Editor  keypad 
layout  (Figure  2-1.) 
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2.7.2.3    Creating  the  Background  Text  -  Steps  6  -  20  — 

6.  Use  the  Downarrow  function  to  move  the  cursor  to  Line  2.  Press  the 
Downarrow  key  once. 

>>>  The  Downarrow  function  moves  the  cursor  straight  down  one  line  at 
a  time.  The  Form  Editor  reports  the  cursor's  new  position  in  Line  24. 

7.  With  the  cursor  on  Line  2  and  Column  1,  type  the  name  of  your  company 
or  any  other  company  name  that  you  would  like  to  use.  Press  the  DE- 
LETE key  to  correct  mistakes. 

8.  Use  the  Leftarrow  function  to  move  the  cursor  hack  to  Line  2  and  'olumn 
L  Press  the  Leftarrow  key  several  times. 

9.  Use  the  INSERT  function  to  set  the  Form  Editor.to  the  insert  mod  '.  Press 
the  9  key  on  the  keypad. 

>>>  The  standard  function  of  the  9  key  on  the  keypad  is  the  INSERT 
function.  The  function  sets  the  Form  Editor  to  the  insert  mode.  The 
abbreviation  INS  replaces  OVS  in  the  modes  section  of  Line  24.  In  the 
insert  mode,  the  Form  Editor  moves  characters  out  of  the  way  of  inser- 
tions rather  than  replacing  the  characters. 

10.  Move  the  company  name  to  the  right  in  Line  2  by  inserting  spaces  at  the 
beginning  of  the  line.  Insert  spaces  until  the  company  name  is  centered  in 
Line  2  on  column  39  or  40.  Hold  the  space  bar  down  for  each  space  that 
you  want  to  insert. 

n.  Use  the  BLINE  function  to  move  the  cursor  to  Line  3  and  Column  1 .  Press 
the  0  key  on  the  keypad. 

The  standard  function  of  the  0  key  on  the  keypad  is  BLINE.  In  the 
advance  mode,  the  BLINE  function  advances  the  cursor  to  the  next  line 
and  Column  L  In  the  backup  mode,  the  BLINE  function  backs  up  (he 
cursor  up  to  Column  1. 

12.  Use  the  following  sequence  of  functions  and  keyboard  keys  to  move  the 
cursor  to  Column  34. 

Press  the  PFl  key  on  the  keypad,  then  type  33  on  the  keyboard,  and 
finally  press  the  Right  arrow  key. 

GOLD  33  Right  arrow 

>>>  The  only  function  (m  the  PFl  key  is  the  COLD  function.  When  vou 
use  the  COLD  function  before  typing  a  number  on  the  keyboard  and  then 
use  another  Form  Editor  function,  the  Form  Editor  repeats  the  last  tunc- 
tion  as  many  times  as  you  have  specified.  In  this  case,  the  Form  Fditor 
repeats  the  Rightarrow  function  33  times  and  the  cursor  moves  from 
Column  1  to  Column  34. 

13.  Type  the  title  of  the  form,  Vendor  Data.  Or  type  any  other  title  that  you 
would  like  to  use.  With  the  cursor  at  Column  34,  the  title  Vendor  Data 
will  be  centered. 
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14.  Move  the  cursor  back  to  Line  2.  Press  the  BACKUP  key  on  the  editor 
keypad,  then  the  BLINE  key  to  get  to  Line  2.  Then  press  the  DELCHAH 
key  to  remove  spaces  and  to  center  the  company  name. 

15.  Move  the  cursor  to  Line  5  and  Column  1.  To  do  this,  use  the  BLINE 
function. 

16.  With  the  cursor  on  Line  5  and  Column  1,  type  the  field  label  for  the 
vendor  number  field,  U  e  n  d  o  r  N  u  m  b  e  r  : . 

17.  Use  the  Rightarrow  function  to  move  the  cursor  to  Column  ',\4.  Press  the 
Rightarrow  key  and  watch  the  column  number  in  Line  24.  You  can  also 
press  GOLD  19  Rightarrow.  Then  type  the  label  for  the  vendor  name 
field,   Namp  ;:  * 

18.  llse  the  Downarrow  and  Leftarrow  functions  to  move  the  cursor  to  Line  6 
and  Column  34,  directly  under  the  N  of  Name  in  Line  5.  Then  type  the 
label  for  the  Vendor  contact  field.  Contact  : . 

19.  Use  the  Downarrow  and  Leftarrow  functions  again  to  move  the  cursor  to 
Line  7  and  Column  .'^4.  Then  type  the  label  for  the  vendor  telephone  field. 

Phone: 

20.  Use  the  Downarrf)W  and  Leftarrow  functions  again  to  move  the  cursor 
down  two  lines  to  Line  9  and  Column  'M.  Then  type  the  label  for  the 
vendor  address  fields.  Address: 

2.7.2.4    Creating  the  Fields  -  Steps  21  -  29  — 

21.  This  and  the  following  steps  create  the  fields  whose  labels  you  have  typed. 
Use  the  BACKUP  function  to  change  the  directional  mode  and  the 
BLINE  function  to  move  the  cursor  back  to  Line  5  and  Column  1.  Press 
the  5  key  on  the  keypad.  Then  the  0  key  on  the  keypad  several  times  until 
the  cursor  is  back  on  Line  5. 

>>>  The  standard  function  of  the  5  key  on  the  keypad  is  the  BACKUP 
function.  The  BACKUP  function  sets  the  P'orni  Editor  to  the  backup 
mode.  The  abbreviation  BCK  replaces  ADV  in  the  modes  section  of  Line 
24.  In  the  backup  mode,  the  BLINF.  function  backs  up  the  cursor  directly 
to  Column  1. 

22.  Move  the  cursor  to  Line  5  and  (^)lumn  15.  Use  the  OVERSTRIKE  func- 
tion and  the  FIP^LD  function  to  set  the  Form  Editor  to  the  overstrike  and 
field  modes.  Press  the  following  sequences  of  keys: 

•  For  the  OVERSTRIKE  functicm,  the  PFl  key  and  then  the  9  key  on  the 
keypad. 

•  For  the  FIELD  function,  the  PFl  key  and  the  8  key  on  the  keypad. 

>>>  The  alternate  function  of  each  keypad  key  is  the  fvuution  whose 
name  is  at  the  bottom  of  the  key  in  the  keypad  diagram.  The  alternate 
function  of  the  9  key  on  the  keypad  is  the  OVERSTRIKE  function,  and 


2-;J2     riu'  KMS   11  Form  Edit<.r  (KKD) 


the  alternate  function  of  the  8  key  on  the  keypad  is  the  FIELD  function. 
To  use  an  alternate  function,  use  the  GOLD  function  first  and  then  press 
the  key  that  controls  the  function  that  you  want  to  use. 

The  OVERSTRIKE  function  sets  the  Form  Editor  to  the  overstrike  mode, 
as  described  earlier. 

The  FIELD  function  sets  the  Form  Editor  to  the  field  mode.  To  create  a 
field,  the  Form  Editor  must  1  in  the  field  mode.  In  the  field  mode,  you 
can  type  only  field  picture  characters  and  field  format  characters. 

The  full  sets  of  field  picture  and  field  format  characters  are  described  later 
in  this  chapter.  In  this  example,  you  will  need  to  use  only  the  field  charac- 
ters that  are  listed  in  Table  2-4. 

2;}.  In  this  example,  vendor  numbers  are  in  the  following  form: 
B -67 -0085 
To  create  the  field  for  the  vendor  number,  type  A    99-9999. 

-^>N  A -99  9  99  9  specifies  the  characters  that  are  valid  for  each  column 
in  the  field;  they  make  up  a  field  picture.  The  picture  specifies  that  the 
first  character  in  the  field  must  be  a  letter  or  a  space  and  the  other 
characters  must  be  digits.  The  hyphens  separate  parts  of  the  field.  For  a 
program  that  processes  the  field  the  hyphens  will  not  be  part  of  the  field 
value.  Therefore,  the  program  only  uses  seven  characters,  although  nine 
display. 

24.  Move  the  cursor  to  Line  5  and  Column  43.  Create  the  vendor  name  field 
by  inserting  the  letter  X  ;^7  times.  The  easiest  way  to  do  this  accurately  is 
with  the  following  sequence: 

COLD  37  X 

Fre.ss  the  PFl  key.  type  'M  on  the  keyboard,  and  press  the  X  key. 

>>N  The  (;()LD  function  sequence  for  repeating  functions  also  repeats 
characters  that  you  want  to  insert. 

Any  character  may  appear  in  a  vendor  name.  Therefore,  the  form  has  to 
allow  any  character. 

25.  Move  the  cursor  to  Line  0  and  Column  43.  Create  the  vendor  contact  field 
by  inserting  the  letter  A  28  times.  Use  the  following  sequence: 

COLD  28  A 

>->N  Assume  that  only  spaces  and  letters  can  appear  in  the  contact  name. 
Periods  ( .)  after  initials  and  abbreviations  will  not  be  copied  from  the  card 
file.  If  an  operator  types  a  period  or  other  invalid  character,  the  Form 
Driver  will  refuse  to  accept  the  character  and  will  signal  the  operator  with 
the  following  mes.sage: 

ALPHABETIC  REQUIRED 
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26.  Move     the     cursor     to     Line     7     and     Column     43     by     pressing 
CiOLD  ^2  Rightarrow.     Create    the    vendor    phone     field    by    typing 

(999)999-9999. 

>>>  Assume  that  only  the  digits  0-9  can  appear  in  a  phone  number. 
When  old  phone  numbers  that  include  letters  in  the  exchange  code  are 
copied,  the  operator  will  convert  the  letters  to  the  corresponding  numbers. 


27 


Move  the  cursor  to  Line  9  and  Column  43  by  pressing  the  Doumar  i  ou 
key  twice,  and  the  <Leftarrow>  until  you  see  43  in  the  Edit  Status  Display 
field  column  on  the  bottom  of  the  screen.  Create  the  first  vendor  address 
field  by  inserting  the  letter  X  28  times. 

>>>  Assume  that  any  character  may  appear  in  an  address. 

28.  To  experiment  with  duplicating  a  field  without  retyping  it,  move  the 
cursor  back  to  the  first  X  in  the  vendor  address  field.  Then  use  the  follow- 
ing sequence  of  functions  to  erase  the  field  picture  and  restore  it  to  the 
form  description: 

COLD  DELP:0L  (iOLD  UNDELLINE 

Press  the  PPT  key.  the  2  key  on  the  keypad,  the  PFl  key  again,  and  the 
PF4  key. 

>>>  The  alternate  functions  of  the  2  and  PF4  keys  are  DELEOL  and 
UNDELLINE.  The  DELEOL  function  erases  the  cursor's  character  and 
the  other  characters  between  the  cursor  and  the  end  ot  the  line.  The  Form 
Editor  stores  the  erasure  in  an  internal  line  buffer,  in  case  you  want  to 
restore  the  last  line  erasure  that  you  make. 

The  UNDELLINE  function  restores  the  string  that  is  in  the  line  bulTer  to 
the  form  description.  Therefore,  when  you  want  to  create  several  fields 
with  the  same  field  picture,  one  easy  method  to  use  is  to  create  one 
picture,  erase  it,  and  then  restore  it  in  as  many  diflerent  positions  as 
needed. 

29.  Move  the  cursor  to  Lines  10.  and  11.  With  the  cursor  in  (^olumn  4;i  in  each 
line,  create  one  ot  the  vendor  address  fields  bv  using  the 
UNDELLINE  function. 


2.7.2.5    Assigning  Field  Attributes  -  Steps  30    -  40  — 

30.  In  this  step  and  the  following  steps,  you  will  compicle  the  Field  Attributes 
questionnaire  for  each  field  that  you  have  created.  To  begin  work  with  the 
Field  Attributes  questionnaire,  enter  the  ASSICN  command.  Use  the  lol- 
lowing  sequence: 

COLD  COMMAND  ASSIGN  ENTER    (or  RETURN) 

>>>  The  alternate  function  of  the  7  key  on  the  keypad  is  the  COMMAND 
lunction.  After  the  COMMAND  function,  the  Form  Editor  erases  Line  24 
and  displays  the  prompt  Comdiand  :  .  When  the  |)ronipt  appears,  enter  a 
command  by  typing  on  the  keyboard  and  use  the  ENTER  function  to 
cause  the  Form  Editor  to  execute  the  command. 
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The  ASSIGN  )mmand  causes  the  Form  Editor  to  display  the  Form  At- 
tributes questionnaire  for  each  new  field.  A  new  field  is  a  field  for  which  no 
tield  attributes  have  been  assigned.  In  this  case,  all  of  the  fields  that  you 
have  created  are  new.  The  first  new  field  is  the  Vendor  Number  field.  The 
Form  Editor  displays  the  Form  Attributes  questionnaire  so  that  you  can 
still  see  the  field  itself  and  then  identifies  the  field  by  replacing  each 
picture  character  with  an  underline  character  (_).  Within  the  Field  At- 
tributes questionnaire,  the  cursor  is  displayed  in  the  first  field  of  the 
questionnaire. 

Like  the  Form-Wide  Attributes  questitmnaire,  the  Field  Attributes  ques- 
tionnaire is  also  an  FMS  form  that  is  displayed  by  the  Form  Driver.  The 
full  set  of  fields  in  the  Field  Attributes  quest itmnaire  is  explained  later  in 
this  chapter.  For  this  example,  the  fields  that  you  need  to  complete  are 
listed  in  Table  2-5. 

;n.  For  the  Vendor  Number  field,  type  the  field  name  Nl^MBER  and  press 
the  TAB  key  to  move  to  the  next  field  in  the  questionnaire.  Press  the 
DELETE  key  to  correct  any  typing  errors. 

>>>  When  the  Form  Driver  is  displaying  a  questionnaire,  the  Form  Driver 
displays  each  character  as  you  type  it.  The  TAB  key  signals  that  you  are 
finished  with  the  Name  field,  although  you  can  return  to  the  field  later 
m-td  change  it.  The  Form  Driver  responds  by  moving  the  cursor  to  the  next 
field  that  you  should  complete.  Table  2-6  lists  the  Form  ^ -iver  editing 
functions  that  you  Vv-ill  need  in  this  example.  The  full  set  of  editing  func- 
tions is  explained  in  Chapter  4. 

;52.  Press  the  TAB  key  four  times.  With  the  cursor  at  the  beginning  of  the 
Help  field,  type  a  short,  helpful  message  that  describes  how  an  operator  is 
to  type  a  vendor  number.  P'or  example: 

C  0  p  y   t  h  e   ^ •'  e  n  d  o  r  ri  i.i  (ti  b  e  r   f  r  o  it)  t  h  e   o  1  d  (.'  e  ii  d  o  r   c  a  r  d . 

Press  the  DELETE  and  LINEFEED  keys  to  correct  mistakes. 

>>>  Each  time  you  i)ress  the  TAB  key.  the  cursor  moves  to  the  next  field 
in  the  questionnaire.  For  the  Right  -Just.  (Mear  Char,  and  Zero  Fill  fields, 
the  default  field  attril)utes  are  unchanged.  'I^herefore.  in  your  new  form, 
ihe  Vendor  Number  field  will  have  the  following  corresponding  attributes: 

•  Not  right  justified. 

•  The  space  is  the  clear  character.  (It  is  better  to  assign  a  clear  character 
such  as  underline  or  if  space  is  used  a.ssign  the  reverse  video  attribute  so 
the  field  is  visible  (m  the  screen.) 

•  Not  filled  with  zeroes. 

The  Default  field  in  the  questionnaire  remains  blank,  riu'relon",  in  your 
new  lorm,  the  Vendor  Number  field  will  not  have  a  default  value. 

'M\.  When  you  ha\e  typed  the  help  mes.sage,  move  the  cursor  to  the  Resp  Re(|d 
field.  With  the  cursor  in  the  Resp  Hvqd  field.  t,\pe  >'  tor  "yes". 
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Table  2-4:    Field  Characters  Required  for  the  Example 


Character 


Usage 


Field-Picture  Characters 

9  For  the  positions  in  the  vendor  niimher  and  telephone  number  where  a 

number  is  the  only  valid  character. 

A  For  the  I'irst  position  in  the  vendor  number,  where  a  letter  is  the  only  valid 

character. 

X  For  the  vendor  name,  contact  name,  and  vendor  address  fields,  where  any 

printable  ASCII  character  is  valid. 

Field-Maker  Character 

(  For  enclosing  the  area  code  in  the  telephone  number. 

)  For  enclosing  the  area  code  in  the  telephone  number. 

For  separating;  the  two  parts  ot  the  telephone  number. 


Table  2-5:     Field  Attributes  Required  for  the  Example 


Attribute 


I'sage 


Delault  To  speiify  the  most  t'ommon  area  code  that  occurs  in  vendor  telephone 

numi)ers. 

Field  name  To  jjrovide  a  unique  identifier  lor  each  field. 

Hel|)  To  provide  reminders  to  the  operator  al)out  com|)letinf;  fields. 

Must  till  To  require  the  operator  to  enter  all  ol  the  characters  in  the  vendor  number 

and  telephone  number. 

Response  lo  require  the  operator  to  enter  the  vendor  numl)er  before  finishinfj  with 

reel ui red  ''ii'  form. 


Table  2-():     Form  Driver  Editing  Functions  Required  in  the  Example 


Function 


BACK.SPACK 

DKI-KIK 

MNKFKKI) 

HKIIKN 

TAK 


Csage 


To  i)ackui)  tnuu  field  to  field  in  a  questionnaire. 
I'd  erase  a  sinjile  character  in  a  (luestionnaire  response. 
To  erase  an  entire  ((uestionnaire  response. 
To  si^jnal  that  all  responses  are  correct  in  a  ((ueslioiuiaire. 
'I'll  advance  from  field  to  field  ui  a  ((ui'stioruiaire. 
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>>>  In  your  new  form,  the  Vendor  Number  is  required  information.  By  • 
typing  Y,  you  assigned  the  response-required  field  attribute.  The  Form 
Driver    responds    by    automatically    moving   the   cursor    to    the    next 
field  —  that  is,  as  if  you  had  pressed  the  TAB  key. 

34.  With  the  cursor  on  the  Must  Fill  field,  type  ^'. 

>>>  In  your  new  form,  the  operator  response  must  fill  the  Vendor 
Number  field.  By  typing  Y,  you  assigned  the  Musi  Kill  attribute.  The 
Form  Driver  responds  by  automatically  moving  the  cursor  to  the  next 
field. 

35.  Press  the  RETURN  key. 

>>>  For  the  field  attributes  after  the  Must  Fill  field,  the  defaults  are 
correct  for  the  Vendor  Number  field.  The  RETURN  or  ENTER  key 
signals  that  you  are  finished  with  the  qucsticmnaire.  The  Form  Driver 
responds  by  displaying  a  fresh  image  of  the  Field  Attributes  question- 
naire. The  Form  Driver  also  identifies  the  next  field  in  your  new  form, 
the  Vendor  Name  field,  as  the  field  to  which  you  should  now  assign  field 
attributes.  The  cursor  appears  at  the  beginning  of  the  Name  field  in  the 
questionnaire. 

36.  Type  UNAME  as  the  field  name.  Move  the  cursor  to  the  Help  field  with 
the  TAB  key  and  type  a  HELP  message  such  as  the  following: 

C 0  p  v  the  V)  e  n  d  0  r  '  5  n  a (ti e  exactly  as  o ri  the  old  u  e n  d  o  r 
c  a  r  ij  . 

>>>  The  other  default  attributes  are  correct  for  the  Vendor  Name  field. 
Therefore,  press  the  RETl'RN  key  when  you  complete  the  HELP  mes- 
sage, The  Form  Driver  identifies  the  next  field  in  your  new  form,  the 
Contact  field,  as  the  field  to  which  you  should  now  assign  field  attrib- 
utes. 

37.  Type  CQNTAC  as  the  field  name.  If  you  want  to  specify  a  HELP  mes- 
sage for  the  Contact  field,  move  the  cursor  to  the  Help  field  and  type 
the  message.  The  other  default  attributes  are  correct  for  the 
Contact  field.  Therefore,  when  the  Name  and  Help  fields  are  complete, 
press  the  RETURN  key. 

38.  Tvpe  the  name  PHONE  for  the  next  field.  Move  the  cursor  to  the 
Default  field  and  type  111  as  the  default  area  code.  Then  move  the 
cursor  to  the  Help  field  if  you  would  like  to  assign  a  HELP  message  tor 
the  Phone  fie'd.  Oiie  ey     ^\e  of  a  HELP  message  is: 


The  area  code   a  ri  d  a  7  -  d  i  3  i  t  n  i.i  (n  b  e  r  a  r  ;?   »■  e  s  u  i  r  t  d . 


>>>  For  the  new  form,  the  default  area  code  is  111,  althovigh  the  design 
does  not  call  for  a  default  number.  With  111  as  the  only  printing  char- 
acters in  the  default  value,  the  field  will  look  like  the  following  example 
when  the  Form  Driver  displays  your  new  form: 


Phone 


(111)   - 
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39.  Assign  the  Must  Fill  attribute  to  the  Phone  field.  Advance  the  cursor  to 
the  Must  Fill  field  and  type  Y.  The  other  default  field  attributes  are 
correct  for  the  Phone  field.  Therefore,  press  the  RETURN  key  when  you 
have  finished  assigning  the  Must  Fill  attribute. 

>>>  Although  the  telephone  number  is  not  required  input  data,  if  the 
operator  types  a  number  all  10  columns  of  the  area  code  and  number 
must  be  complete.  Therefore,  the  Must  Fill  field  attribute  is  assigned 
but  the  Resp  Reqd  field  attribute  is  not  assigned.  Since  this  field  con- 
tains data  already  (the  default  value),  it  is  going  to  have  to  be  filled 
unless  the  default  area  code  is  deleted.  The  way  Must  Fill  works  is  that 
if  a  field  contains  any  data,  it  must  be  filled  —  as  is  the  case  here. 

40.  For  each  of  the  Address  fields  in  your  new  form,  complete  the  following 
procedure: 

•  Assign  field  names  to  each  —  for  example.  ADDRl,  ADDR2.  and 
ADDR:?. 

•  Assign  a  HELP  message,  if  you  would  like  to  do  so. 

•  For  the  other  field  attributes  the  defaults  are  correct.  Press  the  Rp]- 
TURN  key  when  you  finish  assigning  the  field  attributes  for  each 
field. 

When  you  press  the  RETURN  key  after  assigning  the  field  attributes 
for  the  last  Address  field,  you  have  finished  assigning  attributes  to  all 
fields  in  your  new  form.  The  Form  Editor  will  automatically  return  you 
to  the  COMMAND  :   prompt. 


2.7.2.6    Assigning  Video  Attributes  -  Steps  41  -  46  — 

41.  Assigning  video  attributes  is  part  of  the  process  of  editing  a  form  descrip- 
tion. To  illustrate  the  video  attributes,  the  following  steps  guide  you  to 
make  the  following  assignments: 

•  Make  the  company  name  display  in  boldface. 

•  Make  the  Vendor  Number  field  label  and  field  picture  display  in  reverse 
video. 

With  the  COMMAND:   prompt  displayed  in  Line  24,  type  EDIT. 

^^>  The  Form  Editor  responds  to  the  EDIT  command  by  displaying  your 
new  screen  form. 

42.  To  assign  video  attributes  to  character  positions  in  a  form,  you  must  first 
mark  the  i)()sitions  by  putting  them  in  a  .select  range.  Then  you  a.ssign  to 
the  select  range  the  combination  of  video  attributes  that  you  want. 

Move  the  cursor  to  the  first  character  of  your  company  name.  With  the 
cursor  in  that  position,  use  the  SF^LEUT  function.  Press  the  period  (.1  on 
the  keypad. 

>>>  The  Form  Editor  responds  by  adding  information  about  your  select 
range  to  Line  24.  VV'hen  you  are  building  a  select  range,  the  Form  Editor 
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shows  the  line  and  column  number  of  the  cursor's  original  position  when 
you  used  the  SELECT  function. 

43.  Advance  the  cursor  to  the  blank  that  is  at  the  end  of  your  company  name. 
With  the  cursor  in  that  position,  use  the  VIDEO  function.  Press  the  7  key 
on  the  keypad. 

>>>  The  Form  Editor  displays  the  i.'IDEO:  prompt  (m  Line  24. 

44.  To  assign  the  bold  video  attribute  to  the  select  range,  respond  to  the 
UIDEO:  attribute  by  typing  BOLD  and  then  press  the  ENTER  key. 

>>>  The  Form  Editor  immeddiately  displays  the  select  range  in  boldface 
and  again  displays  the  UIDEO:   prompt. 

45.  To  finish  assigning  the  video  attributes,  press  the  ENTER  key  without 
specifying  a  video  attribute.  Then  advance  the  cursor  to  the  V  of  the 
Vendor  Number  and  begin  to  build  a  new  select  range  by  using  the 
SELECT  function. 

>>>  The  Form  Editor  updates  the  line  and  column  numbers  in  the  select 
range  report  in  Line  24. 

46.  Advance  the  cursor  to  the  blank  that  follows  the  field  picture 
(A-99-9399)  for  the  Vendor  Number  field,  and  use  the  VIDEO  func- 
tion. When  the  P^)rm  Editor  displays  the  '.'iDEOs  proiiipt.  type 
REVERSE  and  press  the  ENTER  key.  To  stop  assigning  graphic  attrib- 
utes, press  the  RETL'RN  key  again. 

>>>  The  Form  Editor  responds  by  displaying  the  field  label  and  pictvue  in 
reverse  video. 

2.7.2.7    Assigning  Named  Data  ~  Steps  47  -  50  — 

47.  This  example  assumes  that  you  want  to  experiment  with  your  new  form 
by  having  the  demonstration  program  display  the  form.  To  make  that 
possible,  you  must  assign  named  data  to  your  new  form.  The  demonstra- 
tion program  is  listed  and  explained  in  Appendix  B.  The  named  data  label 
that  you  need  to  assign  is  "NXTFRM"  and  the  named  data  value  to  be 
associated  with  that  label  is  the  string  ".NONE."  Press 
GOLD  COMMAND. 

With  the  COMMAND  :  prompt  displayed  on  Line  24,  type  the  NAME  com- 
mand and  press  the  ENTER  key. 

>>>  The  Form  Editor  responds  by  displaying  the  Named  Data  (Juesticm- 
naire.  The  fields  on  the  left  in  each  line  of  named  data  are  the  tic>lds  for  a 
label  that  are  from  one  to  six  characters  long.  On  the  right  is  the  data 
string  that  is  from  0  to  66  characters  long.  The  label  is  simply  an  identifier 
by  which  a  program  can  request  (the  Form  Driver  searches  not  the 
program)  an  associated  data  string.  The  cursor  is  at  the  beginning  of  the 
first  field  in  the  questionnaire,  the  NAME  field. 

48.  To  enter  the  label,  type  NXTFRM.  To  enter  the  data  value,  press  the 
TAB  kev  to  move  the  cursor  to  the  Data  field  and  then  type  .  NONE  . 
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>>>  As  in  the  other  questionnaires,  the  Form  Driver  is  actually  processing 
the  questionnaire  and  your  responses. 

49.  The  form  does  not  require  any  other  named  data.  Therefore,  press  the 
RETURN  key  to  get  the  COMMAND:  prompt. 

>>>  When  you  press  the  RETURN  key  while  working  with  the  Named 
Data  questionnaire,  the  Form  Editor  displays  the  COMMAND  :  prompt. 

50.  You  have  now  completed  your  new  computerized  version  of  the  sample 
form.  To  save  the  form  description  that  you  have  created,  use  the  SAVE 
command.  Complete  the  following  sequence: 

SAUE  ENTER 

>>>  The  Form  Editor  responds  to  the  SAVE  command  by  saving  your 
new  form  description  in  an  output  file  and  displaying  messages  like  the 
following: 

?  F  E  D  -  F  0  r  (ii  b  e  1  n  3  s  a  >.»  e  d 

The  Form  Editor's  prompt  for  a  command  line  is  also  displayed. 

2.7.2.8    Editing  One  of  the  Demonstration  Forms  -  Steps  51-57  — 

51.  With  the  prompt  displayed,  you  can  continue  to  use  the  Form  Editor  to 
work  on  another  form  description  or  you  can  stop  the  Form  Editor.  The 
following  steps  assume  that  you  want  to  have  the  demonstration  program 
display  your  new  form.  For  the  demonstration  program  to  do  that,  you 
must  modify  the  named  data  for  the  First  form  that  the  demonstration 
uses.  The  First  form  is  a  menu  that  is  illustrated  and  explained  in  Ap- 
pendix B.  The  form  is  named  FIRST  and  is  stored  in  the  form  library  file 
DEMLIB.FLB.  You  need  to  modify  the  form  as  follows: 

•  Add  an  alternative  exercise  to  the  list  in  the  form  by  adding  the  fol- 
lowing line  of  background  text: 

4  Enter   >.'  e  n  d  o  r  data 

•  Add  a  named  data  label  and  value  to  the  other  named  data  that  are 
already  associated  with  the  form.  The  label  and  value  are: 

5  VENDOR 

To  edit  the  form  named  FIRST,  respond  to  the  FED  prompt  by  typing  the 
following  command: 

FED>DEMLIB.FLB(B1!) 

When  the  Form  Editor  responds  with  the  prompt:  Form  name?,  type 
FIRST  and  press  the  RETURN  key. 

>>>  The  Form  Editor  displays  the  screen  image  of  the  form  named 
FIRST  and  the  COMMAND:  prompt.  The  form  has  only  one  field,  the 
single  character  field  following  the  word  Do.  The  field  picture  character  9 
specifies  that  only  numeric  responses  are  valid  for  the  field.  All  other 
characters  in  the  form  are  background  text. 
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52.  Type  EDIT.  Then  advance  the  cursor  to  the  E  in  the  line  that  reads 
4  Exit.  With  the  cursor  in  that  position,  replace  the  word  Exit  with 
Enter  vendor  data.  Check  the  report  in  Line  24  that  you  are  in  the  over- 
strike  mode,  and  type  the  new  phrase. 

>>>  In  the  overstrike  mode,  each  character  that  you  type  replaces  the 
character  at  the  cursor's  position. 

53.  To  restore  the  choice  of  exiting  from  the  demonstration  program,  you  must 
insert  the  Exit  choice.  Advance  the  cursor  to  the  character  position 
directly  below  the  4  and  type  5  Exit. 

54.  The  demonstration  program  uses  the  named  data  that  are  associated  with 
the  forms  in  DEMLIB.FLB  to  transfer  control  from  form  to  form  and  to 
exit.  Therefore,  you  must  now  change  the  named  data  that  are  associated 
with  the  form  named  FIRST  so  that: 

•  The  response  5  stops  the  demonstration. 

•  The  response  4  makes  the  demonstration  display  the  form  named 
VENDOR  and  store  vendor  data  in  an  output  file. 

To  edit  the  named  data  associated  with  the  form  named  FIRST,  enter  the 
NAME  command.  Use  the  following  sequence: 

GOLD  COMMAND  NAME  ENTER 

>>>  The  Form  Driver  displays  the  Named  Data  questionnaire  which  has 
the  data  and  labels  that  are  associated  with  the  form  named  FIRST.  The 
cursor  is  at  the  beginning  of  the  Name  field  in  the  first  line  of  the  ques- 
tionnaire. 

55.  Press  the  TAB  key  several  times  to  advance  the  cursor  to  the  label  associ- 
ated with  .EXIT  (4).  Then,  press  the  LINEFEED  key  to  erase  the  4,  and 
type  5  to  enter  the  new  label. 

>>>  When  the  Form  Driver  is  displaying  a  questionnaire,  press  the 
LINEFEED  key  to  erase  all  of  the  characters  in  any  field.  The  cursor  must 
be  in  the  field  that  you  want  to  erase,  but  it  can  be  at  any  character 
position  in  the  field. 

56.  For  programs  that  use  named  data  labels  to  call  for  data,  the  named  data 
associated  with  a  form  can  be  in  any  order.  Therefore,  to  associate  the 
response  4  with  the  form  named  VENDOR  and  the  appropriate  output  file 
for  vendor  data,  you  can  add  the  new  named  data  at  the  end  of  the 
original  data  that  is  associated  with  the  form.  Do  the  following: 

•  Press  the  TAB  key  until  the  cursor  is  in  the  first  blank  Name  field  of  the 
questionnaire. 

•  Type  the  label  4,  and  press  the  TAB  key  to  advance  the  cursor  to  the 
Data  field. 

•  Type  VENDOR,  the  name  of  the  form  that  is  to  be  displayed  for  the 
response  4  to  the  form  named  FIRST.  Press  the  TAB  key  to  advance  the 
cursor  to  the  next  blank  Name  field. 
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•  Type  4F,  a  special  label  that  the  demonstration  program  will  create,  as 
explained  in  Appendix  B.  Press  the  TAB  key  to  advance  the  cursor  to 
the  Data  field. 

•  Type  SY  :  VENDOR  .  DAT,  or  another  file  name  that  you  want  the  dem- 
onstration program  to  use  for  vendor  data. 

•  To  finish  the  named  data  editing,  press  the  RETURN  key. 

>>>  When  you  press  the  RETURN  key  while  working  with  the  Named 
Data  questionnaire,  the  Form  Editor  displays  the  COMMAND:  prompt. 

57.  To  saue  the  edited  version  of  the  form  named  FIRST,  use  the  SAVE 
command.  Type  SAVE  and  press  the  ENTER  key.  The  Form  Editor  saves 
a  form  description  file  named  FIRST.FRM  an-!  displays  a  message  similar 
to  the  one  illustrated  in  Step  50. 

2.7.2.9    Storing  the  New  Forms  In  a  Form  Library  File  -  Steps  58  -  59  — 

58.  The  preceding  step  is  the  last  one  in  this  example  that  deals  with  the 
Form  Driver  and  Form  Editor.  However,  if  you  want  to  experiment  with 
your  new  form  and  the  edited  version  of  the  form  named  FIRST,  you  must 
add  the  form  descriptions  to  the  form  library  file  DEMLIB.FLB.  The 
FMS  component  that  manipulates  form  descriptions  and  form  library  files 
is  the  Form  Utility  (FUT).  The  Form  Utility  is  described  in  Chapter  3. 
The  following  steps  provide  the  instructions  that  you  need  for  the  forms 
that  you  have  just  edited. 

With  the  Form  Editor  prompt  displayed,  stop  the  Form  Editor  by  typing 
iCTRUzl.  When  the  system  prompt  is  displayed,  start  the  Form  Utility  by 
using  one  of  the  following  commands  or  sequences: 

•  For  RSX-llM  and  llM-PLUS  — 

MCR>RUN  $FLIT'lT) 
or 

FUT® 

•  For  IAS  — 

MCR>FUTiRe!) 

59.  With  the  Form  Utility  prompt  (FUT ;  )  displayed,  type  the  following  Form 
Utility  command  line: 

DEMLIB.FLB --DEMLIB.FLB  .FIRST.FRM  .VENDOR  .  FRM  /  RPiHeTI 

>>>  The  Form  Utility  produces  a  new  version  of  the  form  library  file 
DEMLIB.FLB.  Because  the  command  line  causes  the  new  version  of  the 
form  named  FIRST  to  replace  the  original  version,  the  Form  Utility  re- 
ports the  full  file  specification  of  the  replacement.  The  report  is  a  message 
that  looks  like  the  following: 

DPO:  C220  » 10]  FIRST  .FRM  5  2  Forin  Name  =  FIRST 
For (II  replaced 
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Therefore,  the  new  version  of  the  form  library  file  DEMLIB.FLB  contains 
your  edited  copy  of  the  form  named  FIRST  and  the  new  form  description 
that  you  created  for  the  sample  vendor  data  form.  You  can  use  this  version 
of  DEMLIB.FLB  instead  of  the  distributed  version  when  you  run  the 
demonstration  program. 
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Chapter  3 

The  FMS-11  Form  Utility  (PUT) 


The  Form  I'tility  is  the  only  program  that  creates  and  modifies  FMS  1 1  form 
Hbraries.  Only  the  Form  Utility  should  be  used  when  you  want  to  examine 
FMS  library  files. 

The  P'orm  I'tility  program  provides  the  following  services: 

1.  F^xtracts  and  deletes  form  descriptions  from  form  libraries. 

2.  Combines  form  descriptions  and  form  libraries  into  large  form  libraries. 

.?.    Converts  form  descripti(ms  to  MACRO   11  object  format  for  applications 
that  use  memor\-  resident  forms. 

4.  Produces  printable  data  descriptions  in  COBOL  format  and  listing  files 
for  form  library  directories  and  form  descriptions. 

5.  Creates  form  libraries  from  form  files. 


3.1    Starting  and  Stopping  the  Form  Utility 

You  can  run  the  Form  Utility  in  two  ways: 

1.  By  calling  the  Form  Utility  directly  with  the  task  name  Fl'T.  if  the  Form 
Utility  has  been  installed  as  a  system  utility. 

2.  By  using  the  MCR  command  RUN. 

IAS  users  can  run  the  Form  Utility,  like  the  Form  Flditor,  from  MCR  or  MCR 
mode.  On  IAS  simply  call  the  Form  Utility  with  the  task  name  FUT.  Knsure 
that  FUT  has  been  installed  on  your  system. 

3.1.1    Starting  the  Form  Utility  Directly  with  the  Task  Name  FUT 

With  the  P'orm  Utility  installed  in  your  system,  you  can  call  the  Form  Utility 
directly  by  typing  the  task  name.  The  two  general  formats  of  the  call  are: 

1.  FU  r  filc-spccification-strin^i/optionsl^ij) 

2.  FUT  I 


In  the  first  format,  the  types  of  the  files  in  the  file  specification  string  and  the 
options  that  you  add  to  the  string  specify  a  Form  Utility  process.  The  F»)rm 
Utility  starts  immediately  and  generally  returns  to  the  MCR  >  pr(»mpt  when  it 
finishes  the  process. 

In  the  second  format,  the  Form  Utility  first  displays  the  prompt  FUT  >.  When 
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you  respond  to  the  prompt  by  typing  a  file  specification  string  and  options, 
the  Form  Utility  starts  the  procpss  you  have  specified  and  generally  returns  to 
the  FUT>  prompt  when  finished. 

The  different  forms  of  the  file  specification  string  and  the  options  that  the 
Form  Utility  accepts  are  described  in  later  sections  of  this  chapter. 

3.1.2  Using  the  RSX-11 M/M-PLUS  MCR  RUN  Command 

On  RSX-UM  and  RSX-11  M-PLUS  you  can  also  start  the  Form  Utility  by 
using  the  MCR  RUN  command.  The  command  and  its  options  are  described 
in  the  RSX-1 IM/M-PLUS  MCR  Operations  Manual.  With  the  Form  Utility 
in  the  system  account,  the  general  form  of  the  command  is: 

RUN    *FUTl/()pf/ofi,s]®) 

The  Form  Utility  starts  by  displaying  the  FUT>  prompt.  Later  sections  de- 
scribe how  U)  respond  to  the  prompt. 

3.1.3  Stopping  the  Form  Utility 

The  Form  Utility  stops  in  two  ways.  The  way  it  stops  depends  on  how  you 
start  the  Form  Utility.  The  two  general  cases  are  as  follows: 

1.  When  you  start  the  Form  Utility  with  the  direct  call  FUT  and  include  a 
Form  Utility  command  line.  In  this  case  the  Form  Utility  exits  after 
completing  the  process  you  have  specified  and  the  system  displays  the 
MCR  >  prompt. 

2.  When  you  start  the  Form  Utility  with  the  RUN  command  or  with  the 
direct  call  FUT  without  a  command  line.  In  this  case  the  Form  Utility 
remains  active  after  completing  a  process  and  displays  the  prompt  FUT  >. 
You  can  then  enter  a  new  file  specification  string  or  type  &Ryz)  to  exit. 


3.2    Form  Utility  Defaults 


Table  3-lA  summarizes  the  command  default  values  for  the  Form  Utility  for 
RSX-UM  and  RSX-llM-PLUS. 

Table  3-1  A:    Default  Values  for  RSX-1  IM  and  RSX-llM-PLUS 


Item 


Default 


Input  &  output  The  LOGON  UIC  or  the  UIC  specified  in  the  latest  SET  A^C  command. 
UIC 

Input  &  output  The  volume  installed  in  the  default  device  SY:. 

volume 

Input  file  The  input  file  name  must  be  specified.  The  default  input  file  type  is 

name  &  type  .FLB. 

(continued  on  next  page) 
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Table  3-1 A  (Cont.):    Default  Values  for  RSX-1 IM  and  RSX-1 IM-PLUS 


Item 


Output  file 
name  &  type 


Input  tile 
version 

Output  file 
version 

Option 

Spooling  & 
Block- A  1 ign 
ment 


Default 


With  the  /FF  option,  no  output  file  name  or  type  ran  he  specified.  The 
form  name  hecomes  the  file  name  and  the  file  ty|)e  is  .FRM.  With  the 
/FD  option,  the  form  name  is  the  default  output  file  name.  With  the  /lA 
option,  the  input  form  lihrary  file  name  is  the  default  output  file  name. 
With  the  /CC  option  the  output  extension  is  .LIB.  With  other  options, 
th«>  output  file  name  must  be  specified  and  the  default  file  types  are: 

.FLB  for  any  output  form  library  file. 

.P'MI)  foi  printable  form  descriptions. 

.LIB  for  COBOL  data  descripticms. 

.LST  for  form  library  file  directories. 

.OB.J  tor  MACRO   11  object  module  memory  resident  forms 

The  latest  version  of  the  input  file  that  is  on  the  input  volume. 

Version  1  for  an  entirel"  new  file.  Otherwise,  the  Form  I'tility  assigns  a 
version  number  that  is  one  plus  the  version  number  of  the  latest  version 
that  is  on  the  output  volume. 

The  default  option  is  /FU.  to  produce  a  printable  version  of  a  form  de- 
scription. 

The  /-SP  and  /BA  options  are  the  defaults  for  spooling  and  block-align- 
ment of  form  descriptions.  The  default  is  to  block  align  the  form  library. 


Table  3-lB  summarizes  the  command  default  values  for  the  Form  Utility  for 
IAS. 


Table  3- IB:    Default  Values  for  IAS 


Item 


Default 


Device 
VFD 


Input  file  name 
and  type 

Output  file  name 
and  type 


The  .system  device,  SY:,  or  on  a  timesharing  system  the  default  de- 
vice that  you  specify  with  the  SET  DEFAULT  FDS  command. 

The  default  UFD  is  equivalent  to  the  IJIC  under  which  you  log  in. 
However,  you  can  change  the  default  IT'D  by  specifying  the  FDS 
commands  SET  DEFAULT  (on  a  timesharing  system),  SET  UIC  (on 
a  multi-user  .system),  or  the  MCR  command  SET  A'lC  (on  a  real- 
time .system). 

You  must  specify  the  inp"t  file  name.  The  default  input  type  is  .FLB. 


With  the  /FF  option,  you  cannot  specify  an  output  file  name  or  type. 
The  form  name  becomes  the  file  name,  and  the  file  type  is  .FRM.  The 
default  file  types  are: 

FLB  for  any  output  form  library  file. 
.FMD  for  printable  form  descriptions. 
.LIB  for  COBOL  data  descripticm.^. 
.LST  for  form  library  file  directories. 
.OBJ  for  MACRO  11  object  module  memory  resident  forms. 

(continued  on  next  page) 
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Table  3- IB  (Cont.):    Default  Values  for  IAS 


Item 


Default 


Input  i'ile  version         The  latest  version  ot  the  input  file. 

Output  file  version       Version  1  for  a  new  file.  Otherwise,  the  Form  Utility  assigns  a  version 
number  that  is  one  plus  the  version  number  of  the  latest  version. 


Option 

Spoolinfj  and 
alif^nment 


The  default  option  is  /FD,  to  produce  a  printable  version  of  a  form 
description. 

The  /-SP  and  /BA  options  are  the  defaults  for  spooling  and  block- 
alignment  of  form  descriptions. 


3.3    Form  Utility  Errors 


When  an  error  occurs,  the  Form  Utility  displays  a  message  and  transfers 
control  in  one  of  the  three  following  ways: 

1.  When  recovery  is  impossible,  control  transfers  to  your  operating  system. 

2.  When  recoverable  errors  occur  in  processing  form  descriptions  or  files, 
control  transfers  to  the  FUT>  prompt. 

3.  When  file  specifications  and  options  are  processed  and  completed,  control 
transfers  to  the  FUT>  prompt. 

Appendix  C  lists  Form  Utility  messages  and  explains  how  to  look  messages 
up. 


3.4    Prompts  for  Form  Library  File  Processes 


The  following  six  options  allow  you  to  select  individual  forms  from  form 
library  files  and  process  them  in  different  ways: 

1.  /CC  to  produce  a  COBOL  data  description  structure. 

2.  /DE  to  delete  form  descriptions  from  form  library  files. 

3.  /EX  to  select  specific  form  descriptions  from  one  form  library  file  and 
store  them  in  a  new  form  library  file. 

4.  /FD,  the  default  option,  to  produce  a  printable  form  description. 

5.  /FF  to  select  a  form  description  from  a  form  library  file  and  store  it  in  a 
form  description  file. 

6.  /OB  to  convert  form  descriptions  to  object  format  for  memory  resident 
purposes. 

For  each  of  the  six  options,  the  Form  Utilit>  prompts  you  for  a  form  name. 
The  general  format  of  the  prompt  is  the  full  file  specification  of  the  torm 
library  file  followed  by  the  prompt  Form  nawe'?  For  example,  with  DM0:, 
[30  101,  and  .FLB  as  the  default  input  volume,  UIC,  and  form  library  file  type, 
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and  with  version  6  as  the  latest  version  of  the  form  library  file  DEMLIB,  the 
Form  Utility  would  prompt  you  as  follows: 


MCry  :  FUT     DESCR  . --MD  ^  DEML  I  B  /  FDtREfj 
DM0: [30 » 10]DEMLIB.FLB iG    Form    name' 


You  can  respond  to  the  Form  n  ame'^  :   prompt  by  typing: 

1.  A  valid  form  name  and  pressing  the  Return  key. 

The  Form  Utility  processes  only  the  form  description  for  the  form  name 
that  you  type.  It  then  requests  another  form  name. 

2.  An  asterisk  (*)  and  pressing  the  Return  key. 

The  Form  Utility  processes  all  form  descriptions  that  the  form  library  file 
contains. 

NOTE 

Responding  with  the  asterisk  is  not  valid  when  you  have  speci- 
fied the  /FF  option. 

3.  The  Return  key  only. 

The  Form  Utility  begins  processing  the  next  input  file  that  you  have 
specified,  if  there  is  another  input  file,  or  stops. 


3.5    Form  Utility  Command  Options 

This  section  describes  each  of  the  Form  Utility  command  options.  The  de- 
scriptions are  arranged  in  three  groups,  as  follows: 

1.    Options  for  control  and  HELP. 

The  /ID  option  to  display  the  Form  Utility  identification. 
The  /HE  option  to  display  the  Form  Utility  HELP  file. 
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The  /SP  and  /-SP  options  to  control  spooling  of  the  files  to  the  line 

printer. 

The  /LI  option  to  list  the  names  of  forms  in  form  library  files. 

2.  Options  for  creating  form  library  files. 

The  /BA  and  /-BA  options  to  control  form  description  block  alignment. 
The  /CR  option  to  create  a  form  library  file  by  combining  files. 
The  /DE  option  to  delete  form  descriptions  from  files. 
The  /EX  option  to  extract  form  descriptions  from  files. 
The  /RP  option  to  update  form  descriptions  in  files. 

3,  Options  for  processing  and  converting  form  descriptions. 

The  /Cr  option  to  create  COBOL  data  declarations  for  form  descriptions. 

The  /FD  option  to  create  a  listing  of  a  form  description. 

The  /FF  option  to  create  a  form  description  file  from  a  form  in  a  library 

file. 

The  /OB  option  to  create  MACRO-11  object  modules  of  form  descriptions 

for  memory  resident  forms. 


3.5.1  Options  for  Control  and  HELP 

3.5.1 .1    The  /ID  Option:  Displaying  the  Form  Utility  Identification  —  Use  the  AD 

option  by  itself  in  the  command  line  to  make  the  Form  Utility  display  its 
identification.  The  identification  includes  the  Form  Utility's  task  name 
(FUT),  version  number,  and  patch  level. 

The  following  examples  illustrate  how  the  Form  Utility  responds  to  the  /ID 
option. 


MCR 
FUT 

Mcry 


:  F  U  T  /  I  D  ( 
V  0  1  .  0  0 


MCR)RUN  *FUT(lI) 
FUT>/  ID® 

FUT  yoi.oo 

FUT> 


3.5.1.2  The  /HE  Option:  Using  Form  Utility  HELP  File  —  Use  the  /HE  option  by 
itself  in  the  command  line  to  have  the  Form  Utility  display  a  short  summary 
of  the  Form  Utility  command  line  forms,  as  well  as  a  list  of  the  command  line 
options  and  their  meanings. 

Figure  3-1  shows  how  to  use  the  /HE  option  and  includes  a  copy  of  the  Form 
Utility  help  display.  Later  sections  in  this  chapter  present  the  full  details 
about  the  other  options. 
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Figure  :i-I:    The  /HE  Option  and  the  Help  Display 
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r  V     from     1  i  t'  r  a  r  i  e  s     a  i"i  d     f  o  r  m ' 
5     in     libra  r  ' 

f  r  0  III     1  1  b>  r  a  r  '/ 
5     to     ti  1 1  1  1  d     1  1  b'  r  a  r  v 

f  0  r  (II    d  e  5  c  r  1  p  t  1  n  ri 
III    file     from    a     1  i  t'  r  a  r  •'     f  o  r  iii 

a  1  1  3  n     f  0  r  m  s     i  n     1  i  t'  r  a  r  v 
3    0  n  t  p  n  t     to     line     p  r  i  ri  t  e  r 


fut: 


3.5.1.3   The  /SP  and  /-SP  Options:  Requesting  Line  Printer  Listings  —  Use  the 

/SP  option  with  one  of  the  following  options  to  direct  the  Form  Utility  output 
to  the  default  line  printer  on  your  system: 

•  With  the  /LI  option,  for  form  library  file  directories. 

•  With  the  /FD  opdon,  for  printed  descriptions  of  forms. 

•  With  the  /CC  option,  for  COBOL  data  descriptions  of  forms. 

When  you  use  the  /SP  option,  the  Form  Utility  creates  the  output  file  and 
spools  the  file  to  your  line  printer  after  you  specify  either  the  form  name  or 
indicate  with  an  asterisk  you  want  all  the  forms  listed. 

Use  the  /-SP  option  with  the  same  options  to  explicitly  prohibit  line  printer 
listings.  The  default  option  is  /-SP. 

P"  no  output  file  is  specified  in  the  /SP  option,  then  the  default  output  device 
is  the  terminal,  nut  the  line  printer. 


3.5.1.4   The  /LI  Option:  Listing  Directories  of  Form  Library  Files  —  Use  the  /LI 

option  to  create  a  printable  file  that  lists  the  names  of  the  forms  that  are  in 
form  library  files.  The  output  file  includes  the  following  information: 

1.  The  Form  Utility  identification  and  the  current  date. 

2.  The  full  file  specification  for  the  form  library  file. 
'^.    The  date  the  form  library  file  was  last  updated. 
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4.  The  i-ize  of  the  directory  within  the  lorni  library  file. 

This  directory  size  is  hir^er  than  one  block  only  when  the  file  contains  an 
unusually  larjje  number  ot  forms.  To  use  a  form  library  file  whr>se  direc- 
tory is  larger  than  one  block  in  an  FMS  application,  you  will  need  to 
configure  the  Form  Driver  lor  the  larger  directory. 

5.  For  each  form  description  in  the  form  library  file: 

•  The  form  name  (as  assigned  by  using  the  Form  Kditor). 

•  The  date  the  form  description  was  last  edited  with  the  Form  P^ditor. 

•  The  size  ot  the  impure  area  that  the  form  requires  in  an  application. 

The  following  example  illustrates  the  LI  option  and  the  tormat  of  the  output 
file  that  the  Form  Itilitv  produces.  Because  the  command  line  also  includes 
the  /SF  ()i)tion.  the  Form  Itility  spools  the  output  file  to  the  line  printer  alter 
creating  the  file. 

F  U  T     'J  0  1  .  0  n 
a-  Jf\  N  -  8  0 

Librarv     DM0  :  C  30  *  1  0  1  DEML  I  B  .  F- LB  ?  1     c  r  e  a  t  e  .J  :     4    DEC-TS 
Dire  c  tor/     is     1     t'  1  o  c  f;  s     1  o  ri  d 


Form  Date 


FIRST  d- DEC -79 

CUSTPP  aDEC-79 

LAST  a-DEC-79 

EMPLOY  iJ-DEC-79 

PARTS  4-DEr-79 

CSTO  a-DEC-79 


Impure    Area    (bytes) 


369 

32G 
275 
81  2 
794 
612 


3.5.2  Options  for  Creating   Form   Library  Files 

3.5.2.1    The  /BA  and  /-BA  Options:  Using  Block-Aligned  Form  Descriptions  — 

Use  the  /BA  option  with  one  of  the  following  options  to  explicitly  align  each 
form  descriptiim  from  the  beginning  of  a  block  on  the  output  ma.ss  storage 
volume    (/BA    is   the   default    option): 

•  With  the  /CR   option. 

•  With  the  /DE   option. 

•  With  the   /KX   option. 

•  With  the  /RP   option. 

The   input    form    library   files   can   be    aligned   or   unaligned. 

Block  aligned  form  libraries  may  result  in  faster  access  times  for  an  applica 
tion.  Block-aligned  form  descriptions  require  larger  lorm  library  files  than 
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non-block-aligned  form  descriptions.  The  maximum  increase  in  form  library 
file   size   is    1    block    for  each   form   description. 

In  practice,  block-aligned  form  library  files  are  usually  used  unless  space  is 
severely  limited.  For  example,  if  you  are  packaging  an  FMS  11  application 
with  its  form  library  files  on  RXOl  diskettes  or  other  media  with  small  ca- 
pacity,  you    may   want    to   use   non-block-aligned    form    libraries. 

Use  the  /-BA  option  with  the  same  options  to  prohibit  block-aligned  form 
descriptions. 

Section  3.5.2.2   includes   an   example   of  the  /BA   option. 


3.5.2.2   The  /CR  Option:  Combining  Form  Library  Files  and  Description  Files  — 

Use  the  /CR  option  to  combine  all  input  form  descriptions  in  one  form  library 
file.  The  option  has  no  effect  on  any  of  ihe  input  files.  If  the  Form  Utility  finds 
a  form  name  more  than  once  in  the  input  files  that  you  specify,  the  following 
message   is   displayed: 


FUT 


Illegal     replace  fiient    of    form»    use     /RP 


The  following  example  illustrates  the  /CR  option.  Because  the  /BA  option  is 
also  used,  the  form  descriptions  in  the  output  file  will  be  block  aligned. 


MCR  FUT  DEPT52  .FLB/CR/BA  =  PR0J01  .  ECO  1  2  .  FRM  !  5  .  PRO  J23  REf) 

When  the  Form  Utility  completes  the  command,  the  form  library  iile 
DEPT54.FLB  contains  the  following  form  descriptions: 

•  All    form    descriptions    in    the    latest    version    of   the    form    library    file 
PROJOl.FLB. 

•  The  single  form  description  in  the  form  description  file  EC0I2.FRM;5. 

•  All    form    descriptions    in    the    latest    version    of   the    form    library    file 
PROJ23.FLB. 

3.5.2.3   The  IDE  Option:  Deleting  Form  Descriptions  from  Form  Library  Flies  — 

The  /DE  option  lets  you  delete  some  form  descriptions  from  form  library  files 
and  coTibines  the  remaining  form  descriptions  into  a  new  form  library  file. 

The  Form  Utility  does  not  change  any  of  the  input  files.  For  each  input  file 
that  is  a  form  library  file,  the  Form  Utility  displays  the  full  file  specification 
and  prompts  you  for  the  names  of  the  forms  you  want  to  exclude  from  the 
output  file. 

NOTE 

The  Form  Utility  accepts  form  description  files  as  input  files 
with  the  /DE  option.  However,  none  of  the  form  description 
files  will  be  combined  in  the  output  file.  In  effect,  form  descrip- 
tion files  are  ignored  in  this  case. 


;i-8    The  FMS  11  Form  Utility  (FUT) 


The  following  example  illustrates  the  /DE  option  and  responses  that  exclude 
two  forms  from  each  of  the  input  form  library  files: 


MCR>FUT(RET} 

FUT:FILMGD/DE  =  SLIDE  .FLB!^  .MQi.'IE.FLB  iG'RETi 

[30  .  lOlSLIDE  .FLB  i^  Form    n  ame'^F  I  RST  .REf[ 

[30  tlODSLIDE  .FLB  ;a  Form    n  ame'^SECONDdET] 

[30  » 103SLIDE  .FLB  ia  Form    name'' Set 

FLBiB  Form 

F  L  B  i  G  Form 

F  L  B  ;  B  Form 


DM0 
DM0 
DM0 
DM0 
DM0 
DM0 
FUT 


[30  .10]MDOIE 
[30  .  10]MD>.'IE 
[30  .lODMOUIE 


nameTTHIRD'RFD 
name-^FOURTH® 
n  a  m  e ' 


'  ,het; 


When  the  Form  Utility  finishes,  the  form  library  file  FILMGD.FLB;1  contains 
the  following: 

•  All  of  the  form  descriptions  that  are  in  SLIDE. FLB;4  except  for  the  forms 
named  FIRST  and  SECOND. 

•  All  of  the  form  descriptions  that  are  in  MOVIE. FLB;6  except  for  the  forms 
named  THJRD  and  FOURTH. 


3.5.2.4  The  ,r>i  Option:  Extracting  a  Form  Library  File  —  Use  the  /EX  option  to 
extract  somi;  form  descriptions  from  form  library  files  and  combine  them  in  a 
new  form  library  file.  When  you  include  an  input  file  that  is  a  form  descrip- 
tion file,  the  Form  Utility  also  adds  the  form  description  to  the  output  file. 

The  Form  Utility  does  not  change  any  of  the  input  files.  For  each  input  file 
that  is  a  form  library  file,  the  Form  Utility  displays  the  full  file  specification 
and  prompts  you  for  the  names  of  the  forms  you  want  to  extract. 

The  following  example  illustrates  the  /EX  option  and  responses  to  extract  two 
form  descriptions  from  each  input  form  library  file: 


MCR 
DM0 
DM0 
DM0 
DM0 
DM0 


FUT  PICHLP/EK  =  SLIDE.FLB  \a   ,005HLP.FRM  tMOOIE.FLB  i  G  ReV 

[30  tlODSLIDE.FLB  i^  Form  n  ame'^  00  1  HLP  mi 

[30  .103SLIDE.FLB  ;^  Form  n  ame?  OOZHLPfREI) 

[30  1 10]SLIDE.  FLB  ia  Form  name'^CT 

[30  .  lOlMOOIE  .  FLB  ;G  Form  n  ame'^  OOSHLP® 

[30  .lODMOOIE.FLB  iG  Form  n  ame'' OO^HLP® 


DM0  :  [30  .  10]M0UIE  .  FLB  !B  Form  name'' ML 

mcr:> 

When  the  Form  Utility  finishes,  the  form  library  file  PICHLP.FLB;!  contains 
the  form  descriptions  for  the  forms  named  OOIHLP,  002HLP,  003HLP, 
004HLP,  and  005HLP. 

3.5.2.5    The  /RP  Option:  Updating  Form  Descriptions  In  Form  Library  Files  — 

You  can  use  the  /RP  option  to: 

1.  Replace  a  form  description  that  is  in  a  form  library  file  with  a  new  version 
that  is  in  a  form  description  file. 

2.  Create  a  form  library  file  that  contains  all  of  the  different  forms  (by  form 
name)  that  are  in  several  form  library  files. 
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The  Form  Utility  can  process  the  /RP  option  if  each  form  that  is  stored  in  a 
form  library  file  has  a  unique  name.  The  Form  Utility  processes  the  input  files 
one  at  a  time  from  left  to  right.  For  input  form  descripticms  with  unique  form 
names,  the  output  form  library  file  includes  each  one.  For  input  form  descrip- 
tions with  the  same  form  names,  the  output  form  library  file  includes  only  the 
last  one  processed.  Therefore,  the  final  contents  of  the  output  form  library  file 
in  some  cases  depend  on  the  order  you  use  when  typing  the  input  file  specifi- 
cations. 

Figure  3-2  illustrates  how  the  final  contents  of  a  form  library  file  are  different 
for  two  Form  LUility  commands.  In  the  first  case,  the  last  version  of  the  form 
named  TEST02  that  the  Form  Utility  processes  is  in  the  input  file  TIN.FRM, 
and  the  output  form  library  file  includes  only  that  version  of  TEST02.  In  the 
second  case,  the  last  version  of  TEST02  that  the  Form  Utility  processes  is  in 
the  input  file  T.FLB.  and  the  output  form  library  file  includes  only  that 
version. 

Figure  ;}-2:    The  /RP  Option:  Effects  of  Input  File  Order  on  Output  File 
Contents 


Form  Library 
File  T.FLB 


Form  Description 
File  TIN.FRM 


TUTOa 


TUTOS 


0  ij ''   I   .  ^'  L  f'  -    I   .  F  I   B    '  >"  I  N  .  r  R  MRP 


TCtTOZ 


F  LI  T    T  0 IJ  T  r  .  F  L  t^  M  fJ  .  f  r.M  .  T  .  F  L  B  /  Ty  P 


Output  Form 
Library  File 
TOUTl.FLB 


Output  Form 
Library  File 
T0UT2.FLB 


TeST02 


TEST03 


J 


3.5.3  Options  for  Processing  and  Converting  Form  Descriptions 

3.5.3.1    The  /FF  Option:  Creating  Form  Description  Files  from  Form  Library  Files 

—  Use  the  /FF  option  to  extract  a  form  description  from  a  form  library  file 
and  store  the  description  in  a  form  description  file.  With  this  option,  you  may 
not  specify  an  output  file  name  and  you  may  not  extract  more  than  one  form 
description  at  a  time.  To  create  a  form  description  file  from  a  form  library  file, 
use  the  general  form: 

jnrm -library -filt'-spvi-  /  F  F  1RE|) 


The  Form  Utility  displays  the  full  form  library  file  specification  and  prompts 
vou  for  the  name  of  the  form  that  vou  want  to  extract.  The  Form  Utilitv  then 
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uses  the  form  name  that  you  specify  as  an  output  file  name,  adding  the  file 
type  .FRM. 

In  the  following  example,  the  /¥V  option  extracts  a  form  description  troni  the 
input  form  library  file  I)M0:FRMLIB.FLB;5  in  the  account  [lOO.iU)].  The 
Form  Utility  creates  the  form  description  file  named  HELP  1. FRM. 

>FUT  RET 

FUT  >G  V  :  FRML  I  B  .  F  LB  !  5  /  F  F  ntr 

DM0  :  [  100  .GODFfyMLIB  .  FLB  iB  Form  name"?  HELPIREt: 

FUT> 

3.5.3.2    The  /OB  Option:  Creating  IVIACRO-II  Object  IVIodules  for  Forms  —   Use 

the  /OB  option  to  convert  form  descriptions  to  MACRO- 11  objeci  format.  You 
can  then  task  build  the  object  files  with  your  FMS  applicaticm  to  add  memory 
resident  forms  to  the  application. 

The  Form  Utility  processes  the  input  files  in  the  order  that  you  type  the  file 
specifications.  For  each  input  form  library  file,  the  Form  Utility  prompts  you 
for  the  names  of  the  forms  you  want  to  convert.  Conversion  is  automatic  for 
each  input  form  description  file. 

For  each  form  that  you  specify,  the  P^)rm  Utility  creates  an  object  module 
with  the  following  two  program  sections  PSECTs: 

1.  $FIDX$ 

Contains  the  name  of  the  form  nnd  a  pointer  to  the  beginning  of  the  form's 
data  structure. 

2.  $FORM$ 

Contains  the  form  description,  including  display  attributes,  default  field 
values,  named  data,  and  field  help. 


The  format  used  by  the  Form  Utility  for  the  object  module  is  the  same  as  lor 
the  following  MACRO-11  module: 


F  S  T  rv  : 


.TITLE 
.  I  DENT 

. PSECT 
.RAD50 

.  WORD 


. PSECT 


f  r  ii»  n  a  m 
.'  0  0  1  .  0  0  / 
$FIDX*  .D  .GBL 
/  f  r  III  ri  a  m  , 

F  S  T  R 


$FORM«  'D 


"i  T  1  t  1  e  0  f  t  h  e  m  o  4  u  1  e 

;  F  0  r  III  U  t,  1  1  1  t  '.  1 1  e  r  5  1  0  n  1 1 1 1  m  b  e  i 

;  I  ri  d  e  w  that  the  F  o  r  in  D  r  i  "  e  r  ■  i  -  e  ? 

;  t  0  f  1  ri  d  the  data  struct  u  r  ?'  tor 

;  a  f  0  r  (II  t  h  a  t  1  b  c  a  I.  1  e  4     b  ■'     n  i'  w  c 

;  P  0  1  n  t  e  r  to  the  h  e  3  i  n  u  i  ii  ■?  of  the 

i  f  0  r  (II  d  a  t  a  %  t  r  1 1  c  t  >  i  j-  e 

;  F  n  nil  data  s  t  r  i.i  c  t  n  re  PS  F  C  T 

;  F  0  r  (11 

;       d  a  t  a 

;  b  t  r  u  c  t  ij  r  e 


END 


When  you  specify  more  than  one  form  name,  the  Form  Utility  ccmverts  each 
form  descripti(m  and  produces  a  ctmcatenated  object  module  of  all  the  forms. 
The  following  example  illustrates  the  /OB  option  and  responses  to  convert  one 
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form  description  ironi  the  form  library  file  I)M():[;?(),l()]BIl.L.FLB  and  the 
form  description  file  DM():[30,l{)]BILHLP.FRM  to  object  format: 


>FUT  BILFRM  .  GB.h^DMO:  r  3'"'  .  1"1BII-.L  .FL6  .DM0  :  p  I  LHI  P  •  F  PM  OP  ret 
DM0:  [30  .  lOlBILL  .  FLB  ;G  Form  name'^  <=.!  APTUPKTi 
DM0  :  [30  .  10  IBILL  .  FLB  ;G  Form  name'"'  ret 
MCR 

The  TKB  command  file  order  is  important: 

HLLCBL  .FDOLPM  LB : FOOD AT  .  B  I  LFPM  .  OB  J  . F D VLPM  I  B 

The  Form  Driver  data  module  (FDVDAT)  must  come  before  any  memory 
resident  forms  to  be  included  in  the  task. 


3.5.3.3   The  /CC  Option:  Producing  COBOL  Data  Declarations  for  Forms  —   Use 

the  /CC  opti(,ri  to  produce  an  ASCII  file  that  contains  the  data  declaration 
statements  that  COBOL  applications  require  for  forms.  You  can  then  use  the 
COBOL  COPY  statement  in  the  data  division  of  your  COBOL  program  to 
refer  to  the  files  that  contain  the  data  declaration  statements.  Or  you  can  use 
a  text  editor  to  add  the  data  declaration  statement  file  to  your  COBOL  data 
division. 

For  each  form  that  you  specify,  the  Form  Utility  produces  a  three-level 
COBOL  structure  in  the  Terminal  Format  as  illustrated  in  Figure  '.i-'.V. 
COBOL  also  supports  the  Conventional  (ANS)  Format.  You  can  use  the 
COBOL  REF^ORMAT  utility  to  convert  the  Form  Utility's  data  declaration 
structure  to  the  Conventional  Format.  Refer  to  the  COBOL-U  User's  Guide 
for  a  description  of  the  REFORMAT  utility  and  to  the  COBOL-ll  Language 
Reference  Manual  for  a  description  of  the  Terminal  and  Conventional  For- 
mats. 

Figure  3-8  shows  a  simple  three-field  form  named  PARTS  and  the  COBOL 
data  declaration  structure  that  the  Form  Utility  produces  for  the  form.  As- 
sume that  the  field  names  PARTNO.  DESCRP,"and  SUPPLR  were  assigned 
by  using  the  F'orm  Editor  and  that  the  "Suppliers"  field  has  been  designed  as 
a  verticallv  indexed  field. 


Figure    3-3: 


The    /CC     Option: 
Description 


Illustration    of    the    COBOL    Data 


*     COBOL 

* 

* 

01 
03 


FORM- 
FORM 


■  0  r  (II  L  1  b  r  a  r  v  S  t  r  u  c  t  u  r  e 

This  s  t  r  u  c  t  ij  r  e  c  o  i"i  t  a  i  ri  s  three  t 

F  0  r  (ii  N  a  m  e  <  prefixed  i.-i  i  t  h  "FORM  - 

N  a  m  e  d  t  prefixed  i.i  i  t  h  "  N  •  "  >  a  1 1  d 

D  a  t  a  I  prefixed  i.i  i  t.  h  "  D  "  . 

PARTS-DEF  . 

-PARTS  PH:  >((G)  OALUF 


03  N-PARTS- PARTNO  PIC 

03  D-PARTS-PARTNO  PIC 

03  N-PARTS-DESCRP  PIC 

03  D-PARTS-DESCRP  PIC 

03  N-PARTS-SUPPLP  PIC 

03  D-PARTS-SUPPLR  PIC 


PARTS 
UAL  LIE 


pes  0  f  d  a  t  a  i  t  e  in  < 


);  <  e  ) 
;( (  9  ) 
)( (  G  > 

;<  (  2  G  ) . 

;<(6)  OALUE 


■'PARTNO' 


OALUE  "DESCRP' 


'  S  U  P  P  L  R  ' 


KfZ-^i)  OCCURS  3  TIMES 
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The  following  example  illustrates  the  /CC  option  and  responses  to  produce 
concatenated  COBOL  data  descriptions  for  the  form  that  is  in  the  form  de- 
scription file  DM():[;?().1{)1HELP()4.FRM;2  and  all  forms  in  the  form  lihrary 
file  I)M():(:U),101FRMLIB.FLB;1. 


MCR    FIIT 

f.  .  I    If-  :  PM"  :  [    -•  ■  I  "  IHEI-  F'".-l  .  F'PM  ;Z  .DM'"':  r  T'  •  1 

DM0:  [3''>  .  1 '">1FPML  IB  .  FLB  i  1     Form    name^     *  RfT 

MCR 


IFRML  IB  ,  TLB  !  1   'CC  RfT: 


NOTE 


1.  If  the  same  name  is  used  for  more  than  one  field  in  a  form,  the  COBOL 
compiler  will  flag  one  of  the  fields  as  an  error. 

2.  A  COBOL  data  declaration  cannot  be  created  for  a  form  description  that 
contains  blank  field  names. 


3.5.3.4    The  /FD  Option:  Producing  Form  Descriptions  for  Printed  Listing-  — 

Use  the  /FD  option  to  produce  an  ASCII  file  that  describes  all  of  the  features 
of  a  form.  You  can  print  the  file  that  the  Form  Utility  produces  or  display  it 
on  your  video  terminal. 

The  printable  description  produced  by  the  Form  Utility  is  arranged  m  the 
following  five  major  sections: 

1.  The  form  description  header 

This  .section  lists  all  form-wide  information.  For  example,  the  section  lists 
the  form  name,  the  a.s.sociated  HELP  form  name,  and  the  impure  area  size 
that  the  form  requires. 

In  unusual  cases,  the  Form  Utility  may  also  detect  a  problem  with  a  form 
that  the  Form  Editor  did  not  detect.  In  such  a  case,  the  Form  Utility 
prints  a  brief  summary  of  each  possible  problem  in  this  section. 

2.  The  image  map 

This  section  shows  all  of  the  constant  text  in  the  form  and  the  default 
value  that  has  been  assigned  to  each  field.  When  no  default  has  been 
assigned,  the  image  map  shows  the  clear  character  that  has  been  assigned. 

',\.    The  video  attributes  map 

This  section  shows  the  video  attributes  of  all  C(mstant  text  and  fields  in 
the  form. 

4.    The  field  descriptions 

For  each  field  in  the  form,  this  section  lists  the  field  name,  length,  posi- 
tion, picture,  clear  character,  and  other  assigned  features. 
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.").      I'hc  iianu'd  data  maj) 

This  section  imludi's  a  lull  list  oi  the  iiaint's.  associated  data,  and  order  of 
the  named  data  that  ha\e  heen  assij,'ned  to  the  torni. 

I'he  lollowini;  example  ilhistrates  the    V\)  option  and  responses  to  produce 
printable  desir!|)lions  tor  one  torm  trom  each  ol  two  lorm  library  files: 

MCR     •  UN    $fM  I  RET 

FUT    ro  .  T-  T  "DM':':  f  3"  •  1"  ImM  .  F  I.  P  RfT 

PM<:«:  C30  .  lOIAM.FLB  ;  1     Form  name"^    fHUAWT 

DMn  :  [  10  •  PJ  ]AM  .  FLP  5  1     Form  name-''     nt 

DM"  :  [  30  .  10  1AM  .  HLP  ;  1     Form  r.  ame'^    :_HI""!RfT 

DM0:  [  30  .  t '1 1AM  .HLP  !  1     Form  name"     Rf' 

FUT 

The  toljowin^:  sections  describe  ea(  h  seition  ot  the  output  file  that  the  P'orm 
I'tility  creates  when  you  use  the    Fl)  option. 

3.5.3.5    The   FD  Option:  The  Form  Description  Header  —    Fi^nire  :\   I  shows  an 
example  ol  t  he  torm  description  header  in  a  printable  torm  description. 

Figure  :\-\:    The  /Fl)  Option:  The  Form  Description  Header 


F  0  r  fii    n  a  (II  e  : 

Help     form    1 1  a  m e : 

First     line: 

L.  a  5  t     1  1  ri  e  : 

Date     created: 

Oumer     ID: 

Form     1  e  vi  g  t  h  : 

Number  of  fields: 

1 1?\  p  1 1  r  e  1  r  e  a  size: 


BYE 

BVEHLP 

1 

23 

2g-DEC-79 

0 

l^^B  b. t es 

a 

201 0  b •  I e  s 


The  individual   lines  in  the  f(»r  n  de.scription  header  provide  the  following 
information: 

•  Form  name 

As  assigned  by  completing  the  form-wide  attributes  questionnaire  in  the 
Form  Fditor. 


•  Help  form  name 

As  assigned  by  completing  the  lorm-wide  attributes  (juestionnaire  in  the 
Form  Kditor. 

•  First  line 

.As  assigned  by  completing  the  torm-wide  attributes  ipiestionnaire  in  the 

Form  Kditor. 

•  Last  line 

As  assigned  by  completing  the  torm-wide  attributes  questionnaire  in  the 
Form  Kditor. 
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•  Date  created 

The  most  recent  date  on  which  the  form  was  processed  with  the  F'orm 
Editor. 

•  Owner  ID 

Reserved  for  future  use. 

•  Form  attributes 

If  the  reverse  screen,  current  screen,  and  wide  screen  attributes  have  been 
selected  in  the  form-wide  attributes  questionnaire,  they  are  reported  on  this 
line. 

•  Form  length 

As  reported  in  the  form-wide  attributes  questionnaire  in  the  Form  F^ditor. 

•  Number  of  fields 

The  number  of  fields  with  different  names.  Each  occurrence  of  a  scrolled  or 
indexed  field  is  counted. 

•  Impure  area  size 

As  reported  in  the  form-wide  attributes  questionnaire  in  the  P'orm  Editor. 

3.5.3.6  The  /FD  Option:  The  Image  Map  —  Figure  3-5  shows  an  example  of  the 
80-column  image  map  that  the  Form  Utility  produces  in  a  printable  form 
desvription.  (Although  the  Form  Utility  shows  all  24  lines  in  the  image  map. 
the  tigure  has  been  compressed  for  printing  in  this  manual.) 

Figure  3-5:    The  /FD  Option:  The  Image  Map 


12      3      4      5 
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CUSTOMER  PROFILE 


Annual  Incone  in  Thousands  $000000 
Expected  purchases  $000000 
NuMber  of  eNplo^ees        000000 


For  80-column  forms,  the  borders  of  the  image  map  include  scales  that  show 
the  line  and  column  numbers  for  the  map.  For  i;^2-column  forms,  the  line 
numbers  do  not  appear.  Except  for  the  video  attributes  of  the  form,  the  image 
map  shows  the  form  as  the  operator  will  see  it  before  the  Form  Driver  or  the 
operator  enter  information  in  any  fields.  Each  character  of  the  constant  text 
appears  in  the  correct  line  and  column  position.  Each  field  appears  in  the 
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image  map  with  the  clear  character  that  was  assigned  by  using  the  Form 
Editor,  and  each  field  includes  any  field  marker  characters  such  as  the  hy- 
phen (-). 

3.5.3.7  The  D  Option:  The  Video  Attributes  Map  —  Figure  3-6  shows  an 
example  of  r  .■  8()-column  video  attributes  map  that  the  Form  Utility  pro- 
duces in  a  printable  form  description.  (Although  the  Form  lUility  shows  all  24 
lines  in  the  map,  the  figure  has  been  compressed  for  printing  in  this  manual.) 

Figure  3-6:    The  /FD  Option:  The  Video  Attributes  Map 


Code 
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123456789012345€789012345€789012345€78901234S€789012345<;78 
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2 

3 

4 

5 
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22222222222222222222 
22222222222222222222 
22222222222222222222 


0000000000000000000000000000000222222 
000000000000000000  0222222 
0000000000000000000       222222 


Key  to  Video  Attributes 


A 1 1  r  1  b  I.I  t  e  s 

N  0  r  (ii  a  1 

R  e  "  e  r  s  e  '.'  i  d  e  o 

B  0  1  .d 

Bold-  Reverse  '.'  i  ij  e  o 


For  8()-column  forms,  the  borders  of  the  video  attributes  map  include  scales 
that  show  the  line  and  column  numbers  for  the  map.  For  l.S2-column  forms, 
the  line  numbers  do  not  appear.  Within  the  map,  a  one-digit  or  one-letter 
code  for  the  video  attributes  of  each  character  appears  at  the  character's 
position.  Table  3-2  contains  a  complete  list  of  the  codes  and  their  meanings. 
In  each  map,  the  codes  that  actually  appear  are  described  below  the  map 
under  the  heading  "Key  to  Video  Attributes." 

Table  3-2:     The  /FD  Option:  Video  Attributes  Codes  and  Meanings 


Code 


Meaning 


Normal 
Inderlim' 
Reverse  video 
Inderline.  Reverse  video 


(continued  on  next  page) 
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Table  :)-2  (Cont.):    The  /FD  Option:  Video  Attributes  Codes  and  Meanings 


Code 


Meaning 


0 

(i 


A 
B 
C 
I) 
K 
F 


Hold 

H"ld.  riuierliiie 

Hold,  Reverse  video 

Bold,  Reverse  video.  Inderline 

Blinking 

Blinking,  Underline 

Blinking'.  Reverse  video 

Blinking,  rnderline.  Reverse  video 

Blinking,  Bold 

Blinking,  Bold.  I'nderline 

Blinking.  Bold.  Reverse  Video 

Blinking.  Bold.  Reverse  video.  Inderline 


3.5.3.8  The  /FD  Option:  Field  Descriptions  —  Figure  ^-7  shows  an  example  ot 
the  field  description  that  the  F^orm  Utility  produces  in  the  printable  form 
description. 

Figure  3-7:    The  /FD  Option:  Field  Descriptions 

1     39  Field     IN'v'  of     length     10 

D  1  5  p  1  a  V     a  1 1  r  i  b  u  t  e  s  :     A  u  t  o  t  a  b  •    '■'  e  r  t  i  c  a  1 

Field  Type:  N  n w  e  r i c  <  Scrolled-  1  n  dewed  a  n  d  repeated 

G  t  1  Hi  e  5 

Clear  character:  " @ 

Help  t  e  K  t  :  "I  n  ■ '  o  i  c  e  ri  i,i  m  b  e  r  is     r  e  =i  u  i  r  e  d  i  ri  f  o  r  m  a  t  i  o  ri  ' 

Picture  "a  Imp:  "99999999.99' 

The  individual  lines  in  each  field  description  provide  the  following  informa- 
tion: 

•  Field  name,  size,  and  position 

The  first  line  of  the  field  description  describes  the  starting  position  of  the 
field  in  terms  of  the  row  and  column  numbers  for  the  first  character  ("1  39" 
in  the  example  above).  The  line  also  provides  the  field  name  and  the  length 
of  the  field  as  used  by  the  application. 

•  Display  attributes 

Any  of  the  following  field  attributes,  as  assigned  with  the  Form  Editor: 

—  Autotab 

—  Display  Only 

—  Fixed  Decimal 

—  Full  Required 

—  Vertical  (indexed) 

—  Horizontal  (indexed) 

—  No  Echo 
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—  Right  Justified 

—  Some  Required 

—  Supervise  Protect 

—  Zero  F'\\\ 

•  Field  Type 

The  type  of  characters  that  an  operator  can  enter  in  the  field,  corresponding 
as  follows  with  the  field  picture  characters  that  the  Form  Editor  accepts: 

—  9  Numeric  type 

—  A  Alphahetic  type 

—  C  Alphanumeric  type 

—  N  Signed  numeric  type 

—  X  Any  printing  character 

The  other  field  type  features  listed  in  this  section  are: 

—  Indexed 

—  Mixed  picture 

—  Scrolled 


•  Clear  character 

As  assigned  with  the  Form  F^ditor  field  attributes  questionnaire. 

•  Help  text 

As  assigned  with  the  Form  Editor  attributes  questionnaire, 

•  Picture  value 

As  entered  in  the  Form  Editor's  field  mode. 


3.5.3.9  The  /FD  Option:  The  Named  Data  Map  ~  Figure  3-8  shows  an  example 
of  the  named  data  map  that  the  Form  Utility  produces  in  the  printable  form 
description. 

Figure  3-8:    The  /FD  Option:  The  Named  Data  Map 


Named  Da  t  a  Info  r  in  a  t  i  o  ri 


Name 

ONE 
ONEOUT 


D  a  t  a 

21B  295   23    B  171 
DM2:  [2  .GO] BYWAYS. DAT 


93  END 
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Chapter  4 

Introduction  to  the  FMS-11  Form  Driver  (FDV) 


The  Form  Driver  is  a  library  routine  that  is  a  subcomponent  ot  your  program. 
In  an  application  that  uses  video  images  of  forms  on  the  terminal  screen, 
using  the  Form  Driver  can  reduce  your  programming  effort  by  manipulating 
the  screen,  checking  responses  that  an  operator  types,  and  displaying  help 
messages  and  forms  when  the  operator  requests  them. 

This  chapter  discusses  how  the  F^orm  Driver  interacts  with: 

•  The  form  description,  which  is  created  with  the  Form  Editor. 

•  The  terminal  operator,  who  completes  the  fields  in  a  displayed  form. 

Throughout  the  chapter,  programming  requirements  are  sketched  in  a  general 
way  and  specific  subroutine  calls  are  mentioned  occasionally  but  not  fully 
described.  In  Chapter  5,  the  programming  requirements  are  covered  in  detail 
for  the  different  high-level  languages  and  MACRO- 11.  In  Chapter  6,  the  calls 
are  arranged  in  alphabetical  order  and  the  full  description  is  presented  for 
each  one.  Tn  Chapter  7,  programming  techniques  are  described  for  some  typ- 
ical Form    Jriver  applications. 

4.1    Form  Driver  Interaction  with  the  Form  Description 

This  section  describes  in  a  general  way  how  the  Form  Driver  uses  forms  to 
display  information  for  the  operator,  guide  the  operator  through  a  form,  and 
collect  the  responses  that  the  operator  types.  Throughout  the  section,  and  in 
many  of  the  other  descriptions  in  this  and  lanr  chapters,  the  term  "form" 
refers  to  the  image  that  the  operator  sees  and  to  the  computerized  form 
description  that  the  Form  Driver  handles  internally. 

4.1.1    Media-Resident  and  Memory-Resident  Forms 

Your  program  can  use  form  descriptions  in  two  ways: 

•  As  media-resident  forms,  by  reading  them  directly  from  a  form  library  file 
that  has  been  stored  on  a  mass  storage  volume,  such  as  a  disk. 

•  As  memory-resident  forms,  for  which  the  form  descriptions  are  included 
with  the  program  itself  as  a  part  of  the  task  build  procedure. 

Both  ways  use  form  descriptions  that  have  been  created  with  the  Form  P^ditor 
and  processed  with  the  Form  Utility.  For  example,  after  using  the  Form 
Editor  to  create  a  form  description,  you  must  use  the  Form  Utility  to  store  the 
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description  in  a  form  library  file  or  to  produce  the  objeci  module  that 
memory-resident  usage  requires,  (^hapter  2  describes  how  to  use  the  Form 
Editor,  and  Chapter  ',]  describes  how  to  use  the  Form  Utility.  Chapter  5 
describes  the  task  build  procedure  for  each  language. 

F'or  each  call  to  display  a  form,  the  Form  Driver  checks  the  set  ol  memory- 
resident  forms  first.  When  memory-resident  and  media-resident  form  descrip- 
tions have  the  same  form  name,  the  F^orm  Driver  uses  only  the  memory- 
resident  version. 


4.1.2    Defining  Forms  and  Fieids  by  Name 

The  name  that  you  assign  to  a  form  with  the  F'orm  Editor  is  the  only  informa- 
tion that  the  Form  Driver  needs  to  read  the  Ibrm  from  its  form  library  file  or 
find  its  memory-resident  description.  The  name  that  you  assign  to  a  field  is 
also  all  that  the  Form  Driver  requires,  regardless  of  where  you  locate  the  field 
within  the  form.  As  long  as  changes  to  form  and  field  characteristics  have  no 
effect  on  the  logic  of  your  programs,  you  can  change  the  characteristics 
without  having  to  modify  your  programs. 


4.1.3    Dispiaying  the  Form 

A  typical  procedure  for  displaying  a  form  at  the  beginning  of  an  FMS  applica- 
tion is  as  follows.  (The  calls  are  described  in  full  in  Chapter  6,  and  the 
MACRO-11  procedures  are  explained  in  Chapter  5.) 

1.  If  your  program  uses  media-resident  forms: 

•  Identify  the  I/O  channel  the  P'orm  Driver  is  to  use  for  reading  form 
descriptions  from  the  form  library  file.  With  the  high-level  languages, 
use  the  FLCHAN  call.  With  MACRO  11,  complete  the  Required  Argu- 
ment List. 

•  Open  the  form  library  file.  I'se  the  FLOPEN  call. 

2.  For  all  applications,  identify  an  internal  storage  area,  called  the  impure 
area,  that  the  Form  Driver  is  to  use  for  field  values  and  other  form  require- 
ments. With  the  high-level  languages,  use  the  FINIT  call.  With 
MACRO- 11,  complete  the  Required  Argument  List. 

:i    Display  a  form.  U.se  the  FCT.RSH  or  FSHOW  call. 

The  Form  Driver  provides  two  calls  for  displaying  a  form:  FCLRSH  and 
FSHOW.  The  FCT^RSH  call  clears  the  entire  terminal  screen  before  dis- 
playing a  form.  The  FSHOW  call  clears  only  the  screen  lines  that  are  required 
by  the  form  that  you  want  to  display.  It  you  use  short  forms,  you  can  use  the 
FSHOW  call  to  create  a  screen  display  for  the  operator  that  is  composed  ol 
more  than  one  form  or  part  of  a  Ibrm.  In  this  case,  only  one  form  would 
normally  be  active  for  the  operator,  but  you  could  also  use  special  techniques 
like  the  ones  described  in  Chapter  7  to  keep  more  than  one  form  active  at  a 
time. 
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4.1.4    The  HELP  Function 

Wlu'iu-viT  \(Hir  i)r.)^'rain  isMit-s  a  call  l<«r  an  (.pcratnr  response,  ihe  Form 
Driver  laii  (li>pl;iy  two  levels  n!  help  ii  the  operator  recjuests  it:  hel|)  f«>r  the 
field  m  whicii  the  eursor  is  ioeated  and  help  lor  the  entire  torin.  When  the 
operator  uses  the  Form  Drivers  HKl.P  tuiulion  onee.  the  Form  Driver  dis- 
plays thi'  help  text  tha'  was  t\ped  in  the  Field  .Alt rihiUe  C^iest ionnaire.  I'hen. 
when  the  op^''';"'""  ^'^*'^  ''"'  HKLP  lunction  a^.un.  the  F-Tin  Driver  displays 
the  HKM'  !.-rm  that  was  speeilied  in  the  F..iin-\Vide  .Attributes  (Question- 
naire. 

'I'he  opiM-.Uor  ran  era>e  anv  HKl.r  lonn  and  ha\e  the  Form  Driver  restore  the 
ori^'inal  l.-rm  at  anv  time.  Tlu'  rurs.-r'-  ix.sition  m  the  ori^Mnal  torm  and  all 
field  values  will  he  unchanged. 

For  eaeh  lorm  m  voiir  ap!)lii-at  um,  both  the  help,  text  tor  fields  and  the  HKLP 

forms  have  m  he  >pecified  when  the  f.«rm  is  ereated  or  ehanged  with  the  Form 

Kditor.  For  appliiat ions  that  use  media-resident  forms,  the  HKDP  forms  must 

he  stored  in  the  same  form  library  file  as  the  other  tonus  with  whieh  they  are 

associated. 

Seetion  J.'J.i  describe-  the  WVA.V  tuiution  and  related  function^  in  detail. 

4.1.5    Internal  Storage  of  Field  Values:  The  Impure  Area 

When  you  display  a  form,  the  Form  Driver  stores  its  form  description  inter- 
nally in  a  special  area  called  the  impure  area.  Internal  buffers  are  set  up  for 
the  fields  in  the  display  and  the  other  c  liaracteristics  of  the  form,  such  as  its 
named  data  laluds  and  values.  When  you  issue  calls  to  ^et  or  display  values, 
identify  fields,  and  complete  other  processes,  the  Form  Driver  uses  and  up- 
dates the  impure  area  as  well  as  displaying'  information  lor  the  operator  and 
providing  values  to  your  program. 

Both  the  Form  Kditor  and  the  Form  Itility  report  the  si/.e  of  the  impure  area 
that  is  needed  for  each  specific  form  for  a  M.ACKO  11  application.  For  hi^di 
level  lan^ua^'"  pro<,Tams.  an  additional  M.  bytes  is  reciuired  tor  the  impure 
area.  .MthouKb  yu  lan  vary  the  si/e  ot  the  impure  area  to  match  the  exact 


needs  of  each  form  you  use 
impure  area  ttiat   i^  lar^e  t 


lor  practic.d  purposes  you  need  only  define  one 
■noiitih  lor  the  lar'H'st  form  that  your  application 


ises.  With  the  hi«di-level  lan^'ua^es.  use 


the  FINIT  call  to  define  the  impure 


area 


With  M.ACHO    11.  complete  the  Heciuired  .Argument  List 


le  im|)ure  area 


Is  s 


trictlv  lor  use  In  the  Form  Driver.  N'our  !)roKram  must  not 


ise  it  direct Iv.  ^ou  <  an.  however,  use 


the  FKKTN  and  FKK'IAl-  calls  to  find 


out  any  field  value  as  stored  in  the  impure  area.  The  FKF/i'N  call  returns  the 
value  for  a  specified  field,  and  the  FKK  T.AD  call  returns  a  concatenated  slrinji 
of  the  values  for  all  fields. 


4.1.6    Guiding  the  Operator  Responses 

The  general  principle  that  the  Form  Driver  uses  for  ^niidinj,'  the  (.perator  from 
field  to  field  is  first  from  left  to  ri^ht  within  a  screen  line,  then  line  by  line 
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Irom  the  top  ol  the  torm  to  the  bottom.  However,  the  field  attributes,  such  as 
the  Vertical  Indexed  attribute,  and  the  order  of  calls  that  you  use  usually 
define  a  unique  order  tor  each  form.  In  fact,  your  program  is  entirely  in  control 
ot  the  order  in  which  the  operator  works  with  the  fields. 

For  example,  you  can  control  the  order  completely  by  using  only  the  call  to  get 
the  value  of  a  specified  field,  the  PXIET  call.  By  repeating  the  call  and  speci- 
fying different  fields,  you  require  the  operator  to  complete  the  fields  in  the 
order  that  you  specify. 

You  can  also  allow  the  operator  partial  control  by  using  the  call  that  allows 
him  or  her  to  chc  '^  any  field  in  the  form,  the  FGETAF  call.  The  operator  can 
respond  in  only  one  field,  but  it  can  be  any  of  the  non-Display-Only  fields  in 
the  form.  Since  this  call  also  identifies  the  name  of  the  completed  field,  your 
program  can  then  direct  the  operator  to  any  other  field. 

^'ou  can  also  allow  the  operator  complete  control  over  the  order  in  which  he  or 
she  completes  the  fields  by  using  the  call  for  all  field  values,  the  FGETAL 
call.  The  Form  Driver  returns  the  field  values  to  your  program  and  updates 
the  impure  area  only  when  the  operator  signals  that  the  entire  form  is  com- 
plete. 

4.1.7    The  Order  in  Which  the  Form  Driver  Concatenates  Fields 

Two  of  the  calls  for  operator  responses  get  more  than  one  field  value.  The 
P'GETAL  call  gets  a  concatenated  string  of  all  field  values  for  the  form.  The 
FINLN  call  gets  a  concatenated  string  of  the  field  values  in  one  line  of  a 
scrolled  area.  Regardless  of  the  order  in  which  the  operator  has  entered  and 
corrected  the  field  values,  the  Form  Driver  concatenates  them  according  to 
the  following  conventions: 

1.  F^xcept  for  fields  that  have  the  Vertical  Indexed  attribute,  field  values  are 
concatenated  from  left  to  right  within  each  line  and  then  line  by  line  from 
the  top  of  the  form  to  the  bottom.  This  convention  includes  fields  that 
have  the  Horizontal  Indexed  attribute  and  fields  that  are  in  scrolled  areas. 

2.  Fields  that  have  the  Vertical  Indexed  attribute  are  concatenated  line  by 
line  (in  index  order). 

'■].  W'ithin  the  concatenated  string,  the  length  of  each  field  value  is  the  full 
length  of  the  field.  Each  value  that  is  shorter  than  the  t.eld  is  padded  out 
to  the  field  length  with  the  fill  character  assigned  to  the  field.  For  a  Right 
'Justified  field,  the  fill  characters  precede  the  value,  and  for  a  Left  Justi- 
fied field,  they  follow  the  value. 

Two  calls  display  more  than  one  field  value.  The  FPUTAL  call  displays  all 
field  values  in  the  form.  The  FOUTLN  call  displays  the  field  values  for  one 
line  of  a  scrolled  area.  For  these  calls,  you  must  create  a  concatenated  string 
of  the  values,  including  fill  characters  where  they  are  needed  for  padding.  The 
values  must  be  in  the  same  order  that  the  Form  Driver  would  use  in  pro- 
cessing the  call  to  get  all  field  values. 
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4.1.8  Text,  Field  Marker  Characters,  and  Video  Attributes 

After  displaying  a  form,  the  Form  Driver  normally  uses  only  the  information 
that  relates  to  the  fields,  such  as  a  field  picture,  the  till  and  clear  characters, 
the  default  value,  and  the  line  of  HELP  information.  Unless  the  operator 
requests  the  F'orm  Driver  to  redisplay  the  entire  form  with  the  ('THL/W 
function,  the  F'orm  Driver  makes  no  further  use  of  the  information  that  is  not 
related  to  the  fields,  such  as  the  text  in  the  lorm,  the  tield  marker  characters, 
and  the  video  attributes  of  the  characters  displayed. 

In  particular,  the  field  values  that  the  Form  Driver  returns  do  not  contain  any 
of  the  field  marker  characters  that  the  operator  sees,  such  as  the  hyphen, 
decimal  point,  slash,  and  minus  sign.  Also,  the  field  values  that  your  program 
passes  to  the  F'orm  Driver  to  display  must  not  include  field  marker  characters. 

4.1.9  Processing  Fields 

This  section  describes  how  the  Form  Driver  processes  fields  in  terms  of  the 
tield  attributes. 

4.1.9.1  The  Field  Pictures  —  The  Form  Driver  uses  the  field  pictures  only 
when  the  operator  is  typing  field  values.  The  values  that  your  program  passes 
to  the  Form  Driver  for  dispUiy  are  not  validated  against  the  field  pictures. 

When  the  operator  is  responding,  a  field  picture  is  u.sed  to: 

•  Validate  that  each  character  satisfies  the  requirements  of  the  picture  char- 
acter at  the  corresponding  position.  For  example,  in  a  field  that  has  the 
mixed  picture  999AAA,  the  Form  Driver  accepts  only  digits  in  the  first 
three  positions  and  only  letters  in  the  last  three  positions. 

•  Limit  the  operator's  use  of  the  INSP:RT  and  OVERSTRIKK  modes  of  en- 
tering field  values.  For  example,  the  operator  cannot  change  the  combina- 
tion of  modes  used  for  a  fixed  decimal  field  or  use  the  INSERT  mode  when 
he  or  she  is  completing  a  field  that  has  a  mixed  picture.  (Secticm  4.2.3 
describes  the  INSERT  and  OVERSTRIKE  modes  in  detail.) 

Section  2.6  describes  the  field  picture  characters  and  the  valid  operator  re- 
sponses. 


4.1.9.2    The  Right  Justified  and  Left  Justified  Field  Attributes  - 

Driver  uses  the  Right  Justified  and  Left  -Justified  attributes  to: 


The  Form 


•  Determine  the  position  of  the  cursor  when  it  first  is  displayed  in  a  field.  This 
position,  called  the  cursor's  initial  position,  is  described  in  detail  in  Section 
4.2.2.2. 

•  Align  the  field  value  b<  on  the  screen  and  in  the  impure  area  when  the 
value  is  shorter  than  its  field.  For  example,  the  value  in  a  Right  Justified 
field  always  ends  at  the  last  character  position  in  the  field. 
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•  Determine  when  the  operator  has  filled  the  field  if  the  field  has  the  Autotab 
attribute.  (Section  4.1.8.5  describes  the  effect  of  the  Antotab  attribute  in 
detail.) 

•  Set  the  default  mode  of  entering  values  in  the  field.  For  example,  the  IN- 
SERT mode  is  the  default  for  a  Right  -Justified  field.  (Section  4.2.:?  de- 
scribes the  INSERT  and  OVERSTRIKE  modes  in  detail.) 


4.1.9.3  The  Clear  Character  and  Zero  Fill  Attributes  —  The  Clear  Character 
and  Zero  Fill  attributes  affect  how  field  values  are  padded  on  the  screen  and 
in  the  impure  area.  The  clear  character  is  displayed  and  the  fill  character  is 
used  as  padding  in  the  impure  area.  When  a  field  has  no  value,  it  is  displayed 
with  only  the  assigned  clear  character  and  stored  in  the  impure  area  with  (mly 
the  assigned  fill  character. 

If  a  field  has  the  Zero  Fill  attribute,  the  clear  character  must  be  zero  (0).  and. 
if  necessary,  the  field  value  is  padded  with  zeroes  in  the  impure  area.  The 
Form  Editor  does  not  allow  other  combinations.  If  a  field  does  not  have  the 
Zero  Fill  attribute,  the  clear  character  can  be  any  printing  character,  and.  if 
necessary,  the  field  value  is  padded  with  spaces  in  the  impure  area. 


4.1.9.4  The  Default  Value  —  When  you  display  a  form,  the  Form  Driver 
displays  the  default  field  values  and  stores  them  as  the  current  field  values  in 
the  impure  area.  However,  neither  the  Form  Editor  nor  the  Form  Driver 
validates  the  default  vf  lue  in  any  way.  For  example,  the  Form  Editor  does 
allow  you  to  a.ssign  tie  numeric  default  value  13^^67  for  a  field  with  the 
picture  A  A  AAA,  and  the  Form  Driver  does  display  the  value  in  such  a  case, 
even  though  the  P'orm  Driver  does  not  allow  the  operator  to  enter  the  value. 
Therefore,  when  developing  your  application,  you  must  check  that  the  default 
value  is  correct  for  the  field. 


4.1.9.5  The  Autotab  Attribute  —  When  the  operator  types  the  character  that 
fills  a  field  that  has  the  Autotab  attribute,  the  Form  Driver  terminates  the 
field  as  if  the  operator  had  pressed  the  Tab  key.  (Section  4.2.4  describes  the 
use  of  the  Tab  key  and  the  other  field  terminators.) 

With  respect  to  the  Autotab  attribute,  the  P'orm  Driver  determines  that  a 
field  has  been  filled  as  follows: 

•  The  Must  Fill  attribute,  if  assigned  to  the  field,  must  be  satisfied  (Section 
4.1.8.6  describes  the  Must  Fill  attribute). 

•  For  a  Left  Justified  field,  the  operator  must  have  typed  a  character  in  the 
rightmost  character  position. 

•  For  a  Right  -Justified  field,  the  leftmost  character  position  must  contain  a 
character  other  than  the  Fill  Character. 


4.1.9.6  The  Response  Required  and  Must  Fill  Attributes  —  The  Form  Driver 
uses  the  Response  Required  and  Must  Fill  attributes  to  validate  the  complete- 
ness of  an  operator's  response  in  a  field. 
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In  a  field  that  has  the  Response  Required  attribute,  the  operator  must  type  at 
least  one  character  other  than  the  assigiied  Fill  Character. 

In  a  field  that  has  the  iVlust  Fill  attribute,  the  operator  may  type  nothing  or 
fill  the  field  completely.  The  Form  Driver  will  not  accept  a  field  value  that  is 
shorter  than  its  field  or  a  value  that  contains  a  Fill  Character. 

The  P'orm  Driver  validates  the  Response  Required  and  Must  Fill  attributes  at 
different  times  depending  on  the  call  that  your  program  issues  for  an  operator 
response.  For  the  call  to  get  all  field  values  from  the  operator,  the  Form  Driver 
validates  these  attributes  for  each  field  when  the  operator  terminates  input  in 
the  field  with  the  tab  key  and  when  the  operator  signals  that  he  or  she  is 
finished  with  the  form  by  pressing  the  Enter  or  Return  key.  Foi  the  other 
calls,  the  Form  Driver  validates  these  attributes  when  the  operator  terminates 
the  field.  (Secti(m  4.2.4  describes  how  to  use  the  Knter  and  Return  keys  to 
terminate  a  field  and  also  the  other  field  terminators  in  detail.) 


4.1.9.7    The  Fixed  Decimal  Attribute  —   The  Form  Driver  uses  the  Fixed  Dec- 
imal attribute  to: 

•  Determine  the  position  of  the  cursor  when  it  first  is  displayed  in  a  field.  This 
position  is  called  the  cursor's  initial  position  and  is  described  in  detail  in 
Section  4.2.2.2. 

•  Align  the  parts  of  the  field  value  that  are  to  the  left  and  right  of  the  decimal 
point.  P\)r  example,  the  Form  Driver  displays  the  part  to  the  left  of  the 
decimal  point  as  if  in  a  Right  -Justified  field  and  the  part  to  the  right  as  a 
Left  Justified  field. 

•  Determine  the  fill  and  clear  characters  for  the  left  and  right  parts  of  the 
field.  F'or  example,  the  Form  Driver  always  displays  the  decimal  part  of  the 
field  value  as  if  it  is  in  a  Zero  Fill  and  Left  Justified  field,  regardless  of 
whether  the  Zero  Fill  or  Clear  Character  attribute  is  assigned.  The  Form 
Driver  applies  the  assigned  Zero  Fill  or  Clear  Character  attribute  to  only  the 
part  of  the  value  that  is  to  the  left  of  the  decimal  point. 

Section  4.2.5  describes  the  special  characteristics  of  fixed  decimal  fields  with 
respect  to  typing  and  editing  the  field  values. 


4.1.9.8    The  Horizontal  and  Vertical  Indexed  Attributes  - 

uses  the  Horizontal  and  Vertical  Indexed  attributes  to: 


The  Form  Driver 


Define  the  indexes  for  the  individual  fields  that  make  up  the  indexed  field. 

Move  the  cursor  to  the  proper  individual  field  when  your  program  issues  a 
call  for  the  value  of  a  specific  indexed  field. 

Determine  the  order  in  which  the  cursor  moves  through  the  individual 
fields.  For  example,  when  vour  program  issues  the  call  to  get  all  field  values 
(the  FGF:TAL  call),  the  TAB  function  moves  the  cursor  through  an  indexed 
field  as  shown  in  Figure  4-1.  (Secti<m  4.2.4  describes  the  TAB  function  and 
the  other  field  terminator  functions  in  detail.) 
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•  Determine  the  order  in  which  the  field  values  are  concatenated  for  the  call 
to  net.  all  field  values.  Fii;ure  4   1  illustrates  the  concatenated  order. 

4.1.9.9  The  Display  Only  Attribute  —  The  P'orm  Driver  uses  the  Display  Only 
attribute  to  allow  your  program  to  display  variable  field  values  without  al- 
lowing the  operator  to  type  or  change  the  field  values.  The  Form  Driver  does 
not  allow  the  operator  to  position  the  cursor  in  a  Display  Only  field.  When  the 
operator  uses  the  TAB  function  or  other  functions  to  move  the  cursor  from 
field  to  field,  the  cursor  jumps  past  the  Display  Only  fields  as  if  they  are  part 
of  the  form's  background  text.  (Section  4.2.4  describes  the  TAB  function  and 
the  other  field  terminator  functions  in  detail.) 


4.1.9.10  The  Echo  Off  Attribute  —  The  Form  Driver  u.ses  the  Echo  Off  at- 
tribute to  prohibit  field  values  from  being  displayed  in  fields.  When  the  oper- 
ator responds  in  an  Echo  Off  field  or  when  your  program  issues  a  call  to 
display  a  field  value  in  an  pA'ho  Off  field,  the  P'orm  Driver  returns  the  field 
value  to  your  program  and  stores  it  in  the  impure  area  but  does  not  display  it. 

4.1.9.11  The  Supervisor  Only  Attribute  —  When  your  program  uses  the 
FSPON  call  to  turn  on  the  supervisor-only  mode,  the  Form  Driver  prevents 
the  operator  from  typing  or  changing  values  for  fields  that  have  the  Supervisor 
Only  attribute.  In  effect,  after  the  program  issues  the  FSPON  call,  the  Form 
Driver  treats  all  fields  that  have  the  Supervisor-Only  attribute  as  Display 
Only  fields. 

This  treatment,  which  remains  in  effect  until  the  program  issues  the  FSPOFF 
call,  applies  to  all  forms  that  are  displayed.  When  the  program  issues  the 
FSPOFF'  call,  the  Form  Driver  ignores  the  Supervisor-Only  attribute  until  the 
program  issues  the  FSPON  call  again. 


4.1.9.12  The  Scrolling  Attributes  —  Although  the  Form  Editor  and  Form 
Driver  do  not  allow  you  to  use  a  form  that  is  longer  than  23  screen  lines,  both 
FMS  components  allow  you  to  define  multiline  sections  within  a  form  for 
displaying  data  tables  of  as  many  lines  as  you  need.  Each  of  these  sections  is 
called  a  scrolled  area  because  you  can  use  it  to  treat  your  long  data  table  like  a 
scroll,  winding  it  upward  or  downward  to  expose  in  the  scrolled  area  the 
specific  lines  that  you  want  the  operator  to  see  or  complete.  In  effect,  a 
scrolled  area  is  like  a  separate  window  within  a  form  and  the  terminal  screen. 
In  the  window,  you  can  show  any  part  of  a  longer  file. 

Each  scrolled  area  must  be  at  least  two  lines  long.  Within  one  form  you  may 
define  as  many  separate  scrolled  areas  as  will  fit  within  23  lines.  F^ach  line  can 
have  c;s  many  separate  fields  as  will  fit  on  one  screen  line,  but  for  each  scrolled 
area,  all  lines  must  be  identical  with  respect  to  the  number  of  fields,  their 
sizes  and  attributes,  and  all  other  details. 

Because  the  Form  Driver  can  store  field  values  only  for  the  fields  that  are  on 
the  terminal  screen,  your  program  must  maintain  all  scrolled  area  field  values 
that  are  not  displayed,  that  is,  all  of  the  values  that  are  "above"  and  "below" 
each  scrolled  area.  When  your  program  scrolls  the  lines  of  a  scrolled  area 


4-8    Introduction  to  the  FMS-U  Form  Driver  (FDV) 


• 


upward  or  downward,  the  |)n)f,n-am  must  collect  the  line  of  values  scrolled  out 
of  the  area  and  display  the  line  of  values,  if  any.  scrolled  into  the  area. 

('hapter  7,  Form  Driver  Programming,'  'IVchniques  and  Kxamples.  includes 
more  detailed  explanations  ol  scrolled  area  usajie  and  summaries  ol  typical 
programming  methods  that  apply  to  using  scrolled  areas. 

4.2    Form  Driver  Interaction  with  the  Terminal  Operator 

While  working  with  an  FMS  application,  the  terminal  operator  may  feel  that 
he  or  she  is  constantly  in  control  of  the  form  that  is  displayed  on  the  screen,  hi 
fact,  the  operator  has  no  control  until  your  program  allows  it  hy  issuing  one  ol 
the  tour  Form  Driver  calls  for  an  operator  response.  The  calls  are: 

•  FCIKT.  to  get  the  value  of  a  specified  field. 

•  F(IF/rAF,  to  get  the  value  of  the  field  that  the  operator  chooses. 

•  FCiETAI     to  get  a  concatenated  string  of  all  field  values  for  the  corrent 
form 

•  FINLN.  to  get  a  concatenated  string  ot  all  field  values  lor  a  line  of  a  scrolled 
area. 

Each  of  the  four  calls  puts  the  operator  in  control  until  the  requirements  of 
the  call  are  satislied.  For  example,  alter  your  program  issues  the  F(1ET  call 
for  the  value  of  a  specific  field,  the  operator  can  type  and  correct  the  response 
lor  as  long  as  he  or  she  wishes.  The  operator  also  can  request  help  by  using  the 
HELP  Ivmction.  When  the  operator  terminates  the  tield  l)y  using  a  field  termi- 
nator function  such  as  the  TAB  function,  the  Form  Driver  returns  control  to 
the  program.  Then,  until  the  program  issues  another  call  for  an  operator 
resp<;nse.  the  operator  has  nothing  to  do. 

This  .section  introduces  the  three  general  kinds  of  operator  activity: 

•  Correcting  errors  and  requesting  HELP. 

•  Editing  fields. 

•  Terminating  and  choosing  fields. 


4.2.1    Signaling  and  Recovering  from  Errors 

The  Form  Driver  responds  to  typing  errors  and  invalid  uses  of  the  editing  and 
Held  termination  functions  l)y  ringing  the  terminal  beli  and  by  disi)laying 
messages  on  the  bottom  screen  line.  For  all  errors,  the  Form  Driver  rings  the 
terminal  bell  and  ignores  the  invalid  character  or  function.  For  some  errors, 
the  Form  Driver  also  displays  a  one-line  explanation  on  the  bottom  screen 
line.  For  example,  when  an  operator  tries  to  enter  a  lette.  in  a  field  that  has 
been  designed  to  accept  only  numbers,  the  Form  Driver  rings  the  bell  and 
displays  the  following  message: 

NUMEPIC    REOUirvED 
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Appendix  ('  list>  and  cxplaitis  each  nl  the  nu'ssa^'es  that  can  cip{)Oar  in  these 
eases. 

The  K(»rni  Driver  al>o  provides  a  special  operating  mode.  ealle(1  the  debug 
mode,  that  produce^  an  extensi\e  set  ot frror  mes>a^'es  tliat  are  most  useful 
while  you  are  developin;:  and  retinirji  your  FMS  appluation  proj^rams.  Sec- 
tion T).!  di'scrd)es  the  dehu^'  mode  in  detail.  When  you  are  using  the  Worm 
Driver  with  the  debug  mode  teaturo  and  an  error  oeeurs,  the  Form  Driver 
.•>tops  vour  program,  rings  the  termuial  hell,  (h^plavs  the  (iehug  mode  message 
on  the  Ixtitom  streen  luie.  and  iheii  waii>  lor  mmi  to  |)rcss  t  ne  Knter  or  Return 
key  l)et(tre  re>uming  your  program. 


• 


4.2.1.1    The  HELP  Key  and  Help  Messages—    The  HKl.T  function  can  di     ''.<i\ 

two  le\i'l>  ot  information. 

When  the  operator  presses  the  HKI.l*  kev  for  the  first  time,  the  Form  Driver 
determines  whether  a  help  message  exists  for  the  curren;  field.  If  such  a  one- 
line  help  message  exists,  the  Form  Driver  display>  it  in  the  last  line  oi  tiie 
sifeen.  The  cursor  remains  m  phue  within  the  field. 

If  the  operator  does  not  find  the  onedine  help  message  sut't'iciently  helpful,  he 
or  she  ma>  press  the  HFFP  ke\  a  st-cond  time.  The  Form  Driver  then  di'ter- 
mines  whether  a  help  form  exi.'^t^  tor  tlu'  current  form. 

If  a  help  form  exist.^.  the  Form  Driver  displays  the  help  form  while  saving  the 
context  of  the  current  form.  Faih  help  form  may  have  yet  another  help  form 
associated  with  it.  I'ntil  the  last  oi  a  chain  of  help  forms  is  displayed,  the 
HKId'  func-tion  causes  the  next  form  in  the  chain  to  appear. 

'I'o  return  to  the  form  that  he  or  she  was  originally  working  on.  the  operator 
pres.ses  the  KN'TRK  key.  In  response,  the  Form  Driver  restores  the  f<*rm  and 
cursor  as  they  were  helore  the  HKLF  Key  was  pressed. 

It  no  one-line  help  message  for  a  particular  field  exists,  the  Form  Driver 
displays  tne  help  form  direct Iv.  .-\t  whatever  point  no  help  is  available,  the 
Form  Driver  displays  a  message  to  that  effect  in  the  last  line  of  the  screen. 
When,  in  the  cou  se  of  I'ojitinuing  work  on  the  form,  the  operator  next  t\pes  a 
tield  terminator,  the  Form  Driver  clears  the  last  line. 


# 


4.2.1.2  Messages  Controlled  by  the  Program  —  The  Forri  Driver  (annot 
distinguish  \alid  and  iinalid  operator  responses  in  two  case^ .  First,  although 
the  Form  Driver  acce|)ts  only  the  operator  responses  that  meet  the  reijuire- 
ments  of  the  field  picture  that  was  assigned  with  the  Form  Kditor.  the  Form 
Driver  lannot  detect  a  field  value  that  is  invalid  m  your  application.  Second, 
when  an  operator  uses  i(>rtain  functions  to  terminate  work  with  a  field,  the 
Form  Driver  wails  for  vour  pro^riim  to  rtsfjond  rather  than  automatically 
processing  the  terminator. 

For  both  of  these  eases.  \(iu  can  design  the  program  to  detect  errors  and  other 
conditions  and  displav  messages  to  the  operator.  Chapter  .">  describes  the 
tvpical  processes  and  techni(iues  in  detail. 
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4.2.1.3    Repainting  the  Screen:  The  CTRL/W  Function 

VriOO  Keys:  Hold  down  the  CTRL  key  and  at  the  same  time  press  the  W  key 
on  the  keyboard. 

'I'he  TTKIVVV  limction  repaints  the  current  form  and  its  current  field  values 
on  the  screen.  The  function  is  useful  for  ensurinji  that  the  screen  is  displaying? 
the  field  value-  that  are  stored  in  the  impure  area  and  the  hackj,'round  text  for 
the  form. 

If  part  or  all  of  an  earlier  torm  was  left  on  the  screen  when  the  current  form 
was  displayed,  the  CTRLAV  function  erases  the  earlier  lorm  completely  and 
repaints  only  the  current  form.  (The  FSHOW  call  can  he  used  to  leave  an 
earlier  form  on  the  screen  when  another  form  is  displayed.) 

The  C"TRL/W  function  is  alwavs  valid. 


4.2.2    Field  Editing  Principles  and  Functions 

Table  4-1  summarizes  the  field  editing  functions  that  the  Form  Driver  pro- 
vides and  lists  the  keys  that  control  the  functions.  These  functions  are  exe- 
cuted entirely  by  the  Form  Driver.  You  can  implement  added  functions 
within  your  program  by  switching  the  V'TlOO  to  the  alternate  keypad  mode 
and  using  the  numeric  keypad  keys  to  control  the  functions  that  you  design. 

Table  4-1:     Field   Editing   Keys,    Functions,   and    Usage  for  the  Form 
Driver 


Kei 


Function 


I  sage 


f.ei' arrow 

Ri^litarrovv 

Delete 


("iiisor  Lett 
Cursor  J-JiKht 
Krase  Character 


I>inef'eed 
I'F2 


Krase  Held 

INS1<:RT/ 
OVKRSTRIKK 

HELP 


CTRIVW         Rei)aint  Screen 


Most 
keyboard 

kevs 


Insertion 


Moves  the  cursor  to  the  preceding  character  position  within 
the  tield. 

.Moves  the  cursor  to  the  next  character  position  within  the 
field. 

In  the  INSERT  mode,  erases  the  character  at  the  cursor's 
left  and  closes  the  space. 

In  the  OVKRSTRIKK  mode,  moves  the  cursor  to  the  pre- 
ceding character  position  within  the  field  hut  erases  it  only 
when  the  character  is  the  last  one  in  a  left  justified  field. 

Erases  the  entire  tield. 

Switches  from  the  INSKiri"  mode  to  the  OVKRSTRIKK 
mode,  or  vice  versa. 

First,  displays  the  HKI.P  text  for  the  cursor's  field,  and 
then  displays  succe:  -ive  HKLP  forms  for  the  current  form. 

Repaints  the  screen  with  the  current  form,  field  values,  and 
cursor  location. 

The  keys  lor  the  printing  characters  on  the  keyhoard  in.sert 
their  characters.  In  the  normal  (numeric!  keypad  mode,  the 
numeric  and  punctuation  keys  on  the  keypad  also  insert 
their  characters. 
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4.2.?.1  Relationship  with  the  VT100  Alternate  Keypad  Mode  —  The  VTIOO 
tonninal  can  be  set  to  an  alternate  keypad  mode  or  a  normal  (numeric) 
keypad  mode,  as  described  in  the  VTKH)  I'scr  (luidc.  The  Form  Driver  does 
not  change  the  keypad  mode  at  any  time,  and  regardless  of  the  terminal's 
keypad  mode,  the  editing  and  terminator  functions  are  always  the  same.  If 
your  program  requires  either  of  the  keypad  modes,  you  must  set  the  mode 
from  within  the  program.  Section  o.2  provides  further  information  about  set- 
ting the  a'ternate  keypad  mode  so  that  the  numeric  keys  on  the  keypad  can  be 
used  as  special  tield  terminators. 

4.2.2.2  The  Cursor's  Initial  Position  in  a  Field  —  The  location  of  the  cursor 
when  it  first  is  displayed  in  a  field  is  called  its  initial  position  in  the  field,  i  he 
initial  position  depends  on  whether  the  field  has  the  Right  Justified,  Left 
'Justified,  or  Fixed  Decimal  field  attribute. 

For  Right  -lustified  fields,  the  initial  position  is  just  to  the  right  of  the  last 
character  position  in  the  field.  This  position  is  called  the  hanging  cursor 
position  because  the  cursor  hangs  off  of  the  end  of  the  field. 

For  Left  .lustified  fields,  the  initial  posititm  is  the  leftmost  character  in  the 
field. 

For  Fixed  Decimal  fields,  the  initial  position  is  the  decimal  point.  Section 
4.2.5  describes  the  special  characteristics  of  Fixed  Decimal  fields  with  respect 
to  typing  and  editing  the  tield  values. 

4.2.2.3  Inserting  a  Field  Value:  The  Default  Function 

VTIOO  Keys:  The  Form  Driver  accepts  the  standard  letters,  numbers,  and 
special  characters  on  the  keyboard  that  meet  the  requirements  of  the  field. 

P'or  the  keyboard  keys,  insertion  of  values  in  fields  is  the  default  function.  For 
the  numeric  and  punctuation  keys  on  the  keypad,  insertioii  also  the  default 
when  the  keypad  is  in  the  normal  (numeric)  mode.  In  both  cases,  the  operator 
types  values  as  if  he  or  she  were  using  a  typewriter. 

Insertion  is  invalid  only  when  it  does  not  meet  the  field's  requirements.  For 
example,  letters  are  invalid  where  numbers  are  required,  and  for  a  field  that 
does  not  have  the  Autotab  attribute,  all  characters  are  invalid  when  the  field 
is  full. 


4.2.2.4    Erasing  a  Character:  The  DELETE  Function 

VTIOO  Key:  The  Delete  key  on  the  keyboard. 

The  DELF/IT]  function  normally  erases  the  character  that  is  to  the  left  of  the 
cursor.  The  function  has  different  effects,  however,  in  the  INSERT  and 
OVP]RSTRIKE  modes.  The  modes  are  explained  in  detail  in  Section  4.2.3. 

In  the  INSERT  mode,  the  Form  Driver  erases  the  character  to  the  left  of  the 
cursor  and  closes  up  the  space.  In  a  Left  Justified  field,  the  value  remains  left- 
justified  and  in  a  Right  Justified  field,  the  value  remains  right-justified. 
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In  the  OVERSTRIKE  mode,  the  DELETE  timet  ion  always  mcves  the  cursor 
one  chai.iCter  to  the  left.  However,  to  prevent  an  operator  from  accidentally 
introducing  errors  in  a  field  that  has  a  mixed  picture,  the  function  does  not 
erase  a  character  in  the  OVERSTRIKE  mode  except  for  the  rightmost  char- 
acter in  a  left  justified  field. 

The  DELETE  function  is  invalid  when  the  cursor  is  on  the  leftmost  character 
in  the  field. 

4.2.2.5  Erasing  a  Field:  The  LINEFEED  Function 

VTIOO  Key:  The  Linefeed  key  on  the  keyboard. 

Regardless  of  the  cursor's  position  in  a  field,  the  LINEFEED  function  erases 
all  of  the  characters  (except  for  field  marker  characters)  that  are  in  the  field. 
The  Form  Driver  then  displays  the  assigned  clear  character  for  the  field  and  in 
the  impure  area  fills  the  field  with  the  assigned  fill  character.  When  the 
function  is  complete,  the  cursor  is  located  at  the  initial  position  for  the  field 
(the  leftmost  character  for  a  left  justified  field  and  to  the  right  of  the  right- 
most character  for  a  right  justified  field). 

Errors:  The  Linefeed  function  is  always  valid  input  in  a  field. 

4.2.2.6  Moving  the  Cursor  to  the  Right:  The  Rightarrow  Function 

VTIOO  Key:  The  rightarrow  key  (-)  on  the  keyboard. 

The  Rightarrow  function  normally  moves  the  cursor  one  character  to  the  right 
within  a  field.  However,  the  cursor  always  skips  the  field  marker  characters 
such  as  the  hyphen  (  -  )  and  slash  (  /  )  in  a  field. 

Errors:  The  Rightarrow  function  is  invalid  when  the  cursor  is  to  the  right  of 
the  rightmost  character  in  a  field. 

4.2.2.7  Moving  the  Cursor  to  the  Left:  The  Leftarrow  Funciion  — 

VTIOO  Key:  The  leftarrow  key  (-)  on  the  keyboard. 

The  Leftarrow  function  normally  moves  the  cursor  one  character  to  the  left 
within  a  field.  However,  the  cursor  always  skips  the  field  marker  characters  in 
a  field. 

Errors:  The  Leftarrow  function  is  invalid  when  the  cursor  is  on  the  leftmost 
character  of  a  field. 

4.2.3    Switching  the  Insertion  IVIodes:  The  INSERT/OVERSTRIKE 
Function 

VTIOO  Key:  The  PFl  key  on  the  keypad. 

While  the  operator  is  typing  a  field  value,  the  INSERT  and  OVERSTRIKE 
insertion  modes  control  how  the  Form  Driver  displays  the  characters.  For 
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most  of  the  different  types  of  fields  tliat  can  he  desi^'ned,  the  operator  can 
control  the  insertion  mode  hy  using  the  INSEHT/OV'KKSTRIKK  function. 

When  either  the  operator  or  your  projjram  first  moves  the  cursor  to  a  field,  the 
Form  Driver  sets  the  insertion  mode  according  to  the  attributes  of  the  field. 
The  INSERT  mode  is  the  default  for  right  justified  fields,  and  the  OVER- 
STRIKE  mode  is  the  default  for  left  justified  fields. 

While  the  operator  types  in  the  INSERT  mode  in  a  left  justified  field,  the 
Form  Driver  inserts  each  character  at  the  cursor's  position.  The  cursor,  the 
cursor's  character,  and  all  characters  within  the  field  that  are  to  the  right  of 
the  cursor  are  shifted  to  the  right.  In  a  right  justified  field,  all  characters  to 
the  left  of  the  cursor  are  shifted  to  the  left  and  the  character  is  inserted  to  the 
left  of  the  cursor. 

In  the  OVERSTRIKE  mode,  the  Form  Driver  replaces  the  cursor's  character 
with  the  character  typed  and  moves  the  cursor  to  the  right. 

The  INSERT/OVERSTRIKE  function  switches  the  insertion  mode  from  one 
to  the  other.  For  example,  when  the  Form  Driver  is  initially  in  the  INSERT 
mode,  pressing  the  PFl  key  once  switches  the  Form  Driver  to  the  OVER- 
STRIKE  mode  and  pressing  it  again  switches  back  to  the  INSERT  mode. 

In  fields  that  have  mixed  pictures,  the  INSERT  mode  is  invalid.  In  Fixed 
Decimal  fields,  the  INSERT/OVERSTRIKE  functicni  is  ignored  entirely  be- 
cause of  the  special  data  entry  conventions  that  Fixed  Decimal  fields  require. 
Section  4.2.5  describes  how  the  Form  Driver  handles  operator  respcmses  in 
Fixed  Decimal  fields.  In  all  other  cases,  the  INSERT/OVERSTRIKE  functi(m 
is  valid. 


4.2.4    Field  Terminating  Functions 

The  field  terminating  functions  for  the  Form  Driver  are  the  functions  with 
which  the  operator  signals  that  he  or  she  wants  to  work  with  a  different  field 
or  a  different  form.  The  Form  Driver  processes  these  functions  differently 
depending  on  the  current  F^orm  Driver  call  that  is  being  executed.  In  many 
cases,  the  Form  Driver  gives  your  program  an  opporti  nity  to  intercept  and  in 
effect  change  the  terminator  function  that  the  operator  has  used.  The  way 
that  the  Form  Driver  identifies  each  terminator  function  is  with  a  unique 
terminator  code. 

This  section  describes  the  normal  effects  of  the  terminator  functions  and  lists 
the  terminator  codes  for  both  high-level  languages  and  MACRO-11.  Section 
5.2  describes  the  field  terminator  processing  in  detail,  including  how  to  use 
the  terminator  codes. 

4.2.4.1      Signaling   that   the    Form    Is    Complete:    The    ENTER    and    RETURN 
Functions 

VTIOO  Keys:  The  Enter  key  on  the  keypad  and  the  Return  key  on  the  key- 
board both  control  this  terminator. 
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Terminator  Code  and  Value: 

MACRO   11  Code:  FT$NTH 

High-level  Language  Value;  0 

The  KNTEH  and  RETURN  function.^  signal  that  the  operator  has  completed 
the  current  form.  The  operator  uses  either  tu  net  ion  when  he  or  she  does  not 
want  to  enter  or  change  any  Held  values. 

Vv'hen  an  FCiETAL  call  is  issued,  the  Form  Driver  does  not  accept  either  the 
ENTER  or  the  RETURN  function  until  all  field  values  satisfy  their  field 
requirements.  For  example,  a  Response  Required  lield  must  have  a  response 
and  a  Must  Fill  field  must  be  filled.  However,  the  Form  Driver  cannot  check 
that  the  field  values  are  valid.  You  must  chack  them  in  the  program. 

For  any  other  Form  Driver  call,  control  is  returned  to  the  program  if  the 
requirements  for  the  current  field  value  are  satisfied. 

4.2.4.2    Moving  the  Cursor  to  the  Next  Field:  The  TAB  Function 

VTIOO  Kev:  The  Tab  key  on  the  keyboard. 


Terminator  Code  and  Value: 
MACRO- 11  Code: 


High-Level  Language  Value: 


FT$NXT  (when  terminating  a  field  out- 
side of  a  scrolled  area) 
FT$SNX  (when    terminating    the    last 
field  in  a  line  in  scrolled  area) 
1  (when  terminating  a  field  out- 

side of  a  scrolled  area) 
6  (when     terminating     a     field 

within  a  scrolled  area) 

The  TAB  function  is  only  valid  when  the  requirements  tor  the  current  field 
value  (Response  Required  and/or  Must  Fill)  are  satisfied. 

The  effects  of  the  TAB  function  depend  on  the  Form  Driver  call  that  is  being 
executed. 

For  the  FOETAL  and  FINLN  calls  and  for  the  FGETAF  call  before  the 
operator  enters  or  changes  a  field  value,  the  Form  Driver  processes  the  func- 
tion direct Iv  and  moves  the  cursor  to  the  initial  position  of  the  next  non- 
Display-Oniy  field.  The  order  in  which  the  Form  Driver  moves  from  field  to 
field  is  described  in  Section  4.1.6. 

For  the  FGET  call  and  for  the  FGETAF  call  after  the  operator  enters  or 
changes  a  field  value,  the  F'orm  Driver  transfers  control  to  the  program.  The 
next  call  in  your  program  determines  what  the  operator  sees.  For  example, 
after  the  operator  terminates  a  field  with  ^he  TAB  function,  your  program 
may  display  a  new  form,  calculate  and  display  a  value  in  a  Display  Only  field, 
or  issue  another  call  for  another  operator  response  in  a  specific  field. 

The  function  is  invalid  when  the  cursor  is  in  the  last  non-Display-Only  field  of 
the  form. 
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4.2.4.3    Moving  the  Cursor  to  the  Previous  Field:  The  BACKSPACE  Function 

\"ri(K)  Key:  The  Backspace  key  on  the  keyhoard. 


'IVrminator  C^xle  and  Vahie: 
MACRO  !1  Code: 


PT$FRV  (when  terminating  a  field  out- 
side of  a  scrolled  area) 

P"r$SPR  (when  terminating  the  first 
field   in   a   line   in   a  s-^-rolled 


High-level  Language  Value:  '•] 


area) 

(when  terminating  a  field  out- 
side of  a  scrolled  area) 

(when  terminating  a  field 
within  a  scrolled  area) 


The  effects  of  the  BACKSPACE  function  depend  on  the  Form  Driver  call  tltit 
is  being  executed. 

For  the  F(iETAL  and  FINLN  calls  and  for  the  FGETAF  call  before  the 
operator  enters  or  changes  a  field  value,  the  Form  Driver  processes  the  func- 
tion directly  and  moves  the  cursor  to  the  initial  position  of  the  previous  non- 
Display-Only  field.  The  order  in  which  the  Form  Driver  moves  from  field  to 
field  is  described  in  Section  4.1.(3. 

For  the  FGET  call  and  for  the  FCiETAF  call  after  the  operator  enters  or 
changes  a  field  value,  the  Form  Driver  transfers  control  to  the  program.  The 
next  call  in  your  program  determines  what  the  operator  sees. 

The  function  is  invalid  when  the  cursor  is  in  the  first  non-Display-Only  field 
of  the  form. 


4.2.4.4    Sctulled  Area  IVIoves:  The  Uparrow  Function 

\'T1()()  Keys:  The  Uparrow  key  on  the  keyboard. 

Terminator  Code  and  Value: 

MACRO-11  Code:  FT$SBK 

High-level  Language  Value:  9 

The  Uparr'  w'  function  is  valid  only  when  'e  cursor  is  in  a  field  that  is  within 
a  scrolled  area.  The  function  always  transfer,  control  to  your  program.  There- 
fore, you  can  choose  to  use  the  function  in  any  way  you  wish,  and  the  effects 
that  the  operator  sees  depend  on  the  next  calls  that  your  program  issues. 

The  Form  Driver  processes  the  Uparrow  function  only  when  you  specify  its 
code  in  the  FPFT  call.  The  Form  Driver  either  moves  the  cursor  to  the  pre- 
ceding data  line  within  the  scrolled  area  and  places  the  cursor  at  the  initial 
position  of  the  first  non-Display-Only  field  in  «liat  data  line  or  scrolls  the  arep 
backward  and  places  the  cursor  at  the  initial  position  of  the  first  non-Display- 
Only  field  in  the  current  line. 

When  the  cursor  is  in  the  top  screen  line  of  the  scrolled  area  or  if  the  program 
specifies  data  to  update  the  top  line,  the  Uparrow  function  scrolls  the  bottom 
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• 


scrolled  line  of  int'orniation  olT  the  screen,  scrolls  a  new  line  of  information 
into  the  top  scrolled  line,  <ind  moves  the  intermediate  scrolled  lines  down- 
ward. If  the  cursor  is  in  the  top  line  and  your  program  specifies  values  lor  the 
new  line  of  information,  they  are  displayed;  otherwise,  the  default  field  values 
are  displayed. 

The  function  is  invalid  when  the  cursor  is  in  a  field  thai  is  not  within  a 
scrolled  area. 

4.2.4.5    Scrolled  Area  Moves:  The  Downarrow  Function 

N'TIOO  Key:  The  Downarrow  key  on  the  keyboard. 

Terminator  Code  and  N'alue: 

MACRO  II  Code:  FTSSFW 

High-l(■^el  Language  N'alue:  S 

The  Downarrow  function  is  valid  only  when  the  curso-  is  in  a  field  that  is 
within  a  scrolled  area.  The  function  always  transfers  control  to  your  program. 
Therefore,  you  can  choose  to  use  ^^c  function  in  any  way  you  wish,  and  the 
effects  that  the  operator  sees  depend  on  the  next  calls  that  your  program 
issues. 

The  F'orm  Driver  processes  the  Downarrow  function  only  when  you  specify  its 
code  in  the  FPFT  call.  The  P^)rni  Driver  either  moves  the  cursor  to  the  next 
data  line  within  the  scrolled  area  and  places  the  cursor  at  the  initial  position 
of  the  first  nonT)isplay-Only  field  in  that  data  line  or  scrolls  the  area  forward 
and  places  the  cursor  at  the  initial  position  of  the  first  n<m-Display-Only  field 
in  the  current  line. 

When  the  cursor  is  in  the  bottom  screen  line  of  the  scrolled  area  or  it  the 
program  specifies  data  to  update  the  bottom  line,  the  Downarrow  function 
scrolls  tht  top  scrolled  line  of  information  off  the  screen,  scrolls  a  new  line  ol 
information  into  the  bottom  scrolled  line,  and  moves  the  intermediate  scrolled 
lines  upward.  Il  the  cursor  is  in  the  bottom  line  and  your  program  s|)ecifies 
values  lor  the  new  line  of  information,  they  are  displayed;  otherwise,  the 
default  field  values  are  displayed. 

The  function  is  invalid  when  I  he  cursor  is  in  ;•  field  that  is  not  within  a 
scrolled  area. 


4.2.4.6    Scrolled  .^rea  Moves:  The  EXIT  SCROLLED  AREA  BACKWARD 
Function 

Vi'lOO  Key;  The  PF:)  key  on  the  keypad 

Terminator  Code  and  Value; 

MACKO  11  Co(ie:  FT$XP.K 

High-level  Language  N'alue:  1 

The  KXIT  SCHOLLKD  AKKA  HACKW  AKD  function  is  valid  only  when  the 
cursor  is  in  a  field  that  is  within  a  scrolled  area.  The  function  alwavs  transfers 
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control  to  your  program.  Therefore,  you  can  choose  to  use  the  I'unction  in  any 
way  you  wish,  and  the  effects  that  tiie  operator  sees  depend  on  the  next  calls 
that  your  program  issues. 

The  Form  Driver  processes  the  EXIT  SCROLLP]!)  Ai^EA  BACKWARD  func- 
tion only  when  you  specify  its  code  in  the  VPVT  call.  The  Form  Driver  moves 
the  cursor  to  the  initial  position  of  the  first  nonT)isplay-Only  field  above  the 
scrolled  area. 

The  function  is  invalid  when: 

1.  The  cursor  is  in  a  field  that  is  not  within  a  scrolled  area. 

2.  There  is  no  n()nT)isplay-Only  field  above  the  scrolled  area. 


4.2.4.7    Scrolled  Area  Moves:  The  EXIT  SCROLLED  AREA  FORWARD 
Function 

VTIOO  Key:  The  PF4  key  on  the  keypad. 

Terminator  Code  and  Value: 

MACRO- II  Code:  FTSXFW 

High-level  Language  Value:  ."> 

The  EXIT  SCROLLED  AREA  FORWARD  function  is  valid  only  when  the 
cursor  is  in  a  field  that  is  within  a  scrolled  area.  The  function  always  transfers 
control  to  your  program.  Therefore,  you  can  choose  to  use  the  function  in  any 
way  you  wish,  and  the  effects  that  the  operator  sees  dei)en(i  on  the  next  calls 
that  your  program  issues. 

The  F'oim  Driver  processes  the  EXIT  SCROLLED  AREA  FORWARD  func- 
tion only  when  you  specify  its  code  in  the  FPFT  call.  The  Form  Driver  moves 
the  cursor  to  the  initial  positi(<n  of  the  first  non-Display-Only  field  below  the 
scrolled  area. 

The  function  is  invalid  when: 

L    The  cursor  is  in  a  field  that  is  not  within  a  .scrolled  area. 

2.    There  is  no  non-Display-Only  field  below  the  scrolled  area. 


4.2.5    Typing  and  Editing  Fixed  Decimal  Values 

The  cursor';';  initial  position  for  a  Fixed  Decimal  field  is  the  decimal  point  that 
the  Form  Driver  displays.  The  decimal  point  is  a  field  marker  character.  It  is 
not  stored  in  the  impure  area  or  returned  to  your  program  as  part  of  the  field 
value. 

As  the  operator  types  a  Fixed  Decimal  value,  he  or  she  sees  the  Form  Driver 
treat  the  left  part  as  if  it  is  in  a  Right  -histified  field  and  the  right  part  as  if  it 
is  in  a  Left  .Justified  field.  With  the  cur.sor  at  the  initial  position,  the  Form 
Driver  displays  the  first  digits  that  the  operator  types  in  the  part  of  the  field 
that  is  to  the  left  oi  the  decimal  point  until  the  operator  actually  types  a 
decimal  point.  Then  the  Form  Driver  displays  the  digits  that  the  operator 
types  in  the  part  of  the  field  that  is  to  the  right  of  the  decimal  point. 
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As  the  operator  edits  a  Fixed  Decimal  value,  the  LINEFEED  function  erases 
the  entire  value  and  leaves  the  cursor  at  the  initial  position.  The  DELETE 
function  also  erases  the  digits  in  the  field  value  normally.  However,  with  the 
cursor  just  to  the  right  of  the  decimal  point,  the  DELETE  function  moves  the 
cursor  hack  to  the  decimal  point  hut  does  not  erase  it. 


• 
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Chapter  5 

Form  Driver  Programming  Requirements  and 
Concepts 


This  chapter  provides  a  technical  overview  of  the  Form  Driver  for  the  high 
level  language  and  MACRO-11  programmer.  (Although  this  chapter  discusses 
the  Form  Driver  calls  in  several  sections,  the  principal  description  of  each  call 
is  in  Chapter  6.) 

The  topics  in  this  chapter  are  arranged  in  three  general  groups: 

•  First,  information  such  as  checking  the  status  of  Form  Driver  calls  and 
using  field  terminator  features,  thf.  '3  important  to  all  programmers  who 
design  or  write  Form  Driver  applications. 

•  Second,  information  that  applies  only  to  the  high-level  languages.  The  sec- 
tions in  this  group  cover  BASIC-PLUS-2,  COBOL-11,  FORTRAN  IV,  and 
FORTRAN  I\'-PLUS,  in  that  order.  The  section  for  each  language  describes 
the  data  types,  syntax  requirements,  arguments  used,  and  typical  proce- 
dures for  task  building  an  FMS  application  program. 

•  Finally,  information  that  applies  only  to  MACRO-11. 


5.1    Features  for  Checking  Call  Status 

To  improve  the  effectiveness  of  FMS  applications  and  reduce  the  time  re- 
quired for  you  to  produce  fully  debugged  applications,  the  Form  Driver  main- 
tains the  completion  status  of  each  call  and  provides  four  general  ways  for  you 
to  obtain  the  status: 

•  For  high-level  language  applications,  the  FSTAT  call  returns  the  Form 
Driver  status  code  for  the  last  call  that  was  processed.  The  F'STAT'  call  also 
returns  the  FCS  or  RMS  system  error  code  when  a  call  fails  because  of  an 
error  in  opening  or  reading  a  form  library  file. 

•  For  MACRO-11  applications,  a  2-word  status  block  holds  the  Form  Driver 
and  system  status  codes  for  the  last  call  that  was  processed. 

•  For  added  support  while  an  FMS  application  is  being  developed,  a  special 
debug  mode  is  available  for  displaying  explicit  messages  about  the  status  of 
calls. 

•  For  customized  support  of  FMS  applications  in  the  field,  the  FPUTL  call 
can  be  used  to  signal  the  application  operator  about  program  conditions 
with  any  message  that  you  think  is  appropriate. 
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5.1.1    Form  Driver  and  System  Status  Codes 

Table  5-1  lists  and  describes  the  status  codes.  For  FMS  applications  in  high- 
level  languages,  the  FSTAT  call  returns  one  of  the  listed  numeric  codes  in  the 
first  of  its  two  status  arguments.  For  applications  in  MACRO-U,  DIGITAL 
recommends  that  you  use  the  listed  global  symbols  instead  of  the  numeric 
codes  in  order  to  ensure  greater  application  compatibility  with  later  versions 
of  FMS  software. 

Two  of  the  status  conditions  listed  in  Table  5-1  indicate  an  error  in  trying  to 
open  or  read  a  form  library  file  (code  values  -4  and  -18).  In  these  two  cases, 
the  FSTAT  call  also  returns  (in  the  second  status  argument)  FCS  or  RMS 
system  error  codes  that  help  to  define  the  exact  cause  of  the  problem.  For  the 
full  list  of  FCS  system  errors,  refer  to  the  RSX-l  IM/M-PLUS  I/O  Operations 
Manual  or  the  IAS/RSX-11  I/O  Operations  Reference  Manual.  For  RMS  er- 
rors, refer  to  the  RMS-1 1  User's  Guide. 

Note  that  the  status  code  FE$DLN,  value  -16.,  (data  specified  too  long  for 
output)  is  returned  to  the  program  only  in  Debug  Mode.  Regardless  of 
whether  the  Form  Driver  provides  support  for  Debug  Mode,  the  specified  data 
is  truncated  when  displayed  and  the  Form  Driver  completes  the  call  in  the 
normal  way. 

Table  5-1:    Summary  of  Returned  Status  Values  and  Codes 


Status  Value 

in  High-Level 

Status 

Code 

Languages 

(MACRO 

11) 

Meaning 

(decimal) 

1. 

FS$SUC 

Successful  completion. 

2. 

FSSINC 

Current  form  incomplete. 

-  1. 

FESFCp 

Specified  function  code  undefined. 

-  2. 

FE$IMP 

Impure  area  too  small. 

-  3. 

FE$FSF 

Invalid  file  specification. 

-  4. 

FE$IOL 

Error  encountered  opening  form  library  (an 

-  5. 

FE.$FLB 

-  6. 

FE$ICH 

-  7. 

FE$FCH 

-8. 

fe.$fr:vi 

-  9. 

FE.f;FNM 

-10. 

FE$LIN 

FCS  or  RMS  system  error  code  that  provides 
more  detail  can  he  found  with  the  FSTAT  call 
and  is  returned  in  the  second  word  of  the 
Status  Block  I. 

Specified  file  not  form  library. 

Invalid  channel  number  specified. 

Form  library  not  open  on  s()ecified  channel. 

Invalid  form  definition. 

Specified  torm  does  not  exist. 

Invalid  first  line  number  to  display  form. 

(continued  on  next  pa^e) 
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Table  5-1  (Cont.):    Summary  of  Returned  Status  Values  and  Codes 


• 


Status  Value 

in  High-Levcl 

Status  Code 

Languages 

(MACRO   Ci) 

(decimal) 

-11. 

KESFLI) 

-12. 

FK.SNOF 

-13. 

FKsDSI' 

-14. 

FE.SNSC 

-15. 

FE$I)NM 

-16. 

FE$I)LN 

-17. 
-18. 


Meaning 


FESITH 

fp:$ior 


-19. 

FHl.SIFN 

-20. 

None 

-21. 

NniH' 

-22. 

\:in(^ 

SiJi'cilied  tield  (U)v>  not  exist  (invaiid  field 
name  or  index  I. 

N'd  lields  delined  tnr  rurrent  tnrni. 

(iei  call  ille^'al  Idi^  dis|)la>'  only  t'ield(s). 

Si)('(itied  lield  nut  in  scrolled  area. 

Named  fiata  specified  does  not  exist. 

Data  specil'ied  loi'  output  too  long  (tnuuated 
by  Form  Driven,  ihis  error  is  returned  In'  the 
Form  Driver  only  when  Del)UK  Mode  Supjjort 
is  included. 

I  ndefined  lield  terminator. 

Error  encountered  readin<;  form  library  (an 
FCS  or  RMS  system  error  code  that  provides 
more  detail  can  l)e  tound  with  the  F.S'I'AT  call 
and  is  returned  in  the  second  word  ot  the 
Status  Block) 

Spi'citied  call  iinalid  m  current  context  of 
iorm. 

(For  hit,'h-le\'el  lanjiuage  programs  only) 
Wrong  ni"  i)er  ot  arguments  in  call. 

I  For  high  level  language  programs  onlvi  Im- 
pure area  not  yet  initialized. 

(BASIC  I'l.lS  2  onlvl  Hi'lurned  string  is 
longer  than  the  declared  variable  length. 


5.1.2    Debug  Mode  Support  for  Application  Development 

The  Form  Driver  dehu;:  mode  is  availal)le  to  both  liiKh-level  lan^niaf^e  and 
MACRO  11  programmers.  'I'he  debug  mode  is  a  Form  Driver  lonliguratioii 
option  that  adds  ex!)H(it  messages  lor  the  status  conditions  to  the  P'orm 
Driver.  Chapter  S  describes  the  configuration  dialogue  and  procedure  in  de- 
tail. I'sually.  programmers  who  want  debug  mode  sup|)ort  configure  a  version 
of  the  Form  Driver  that  inchides  that  support  as  well  its  another  version  that 
does  not  include  it.  Then  the  version  with  the  debug  mode  support  is  used 
during  application  de\elopment  and  the  version  without  the  debug  mode 
support  is  used  for  final  testing  and  distribution. 

In  the  debug  mode,  the  Form  Driver  rings  the  !ertjiinal  bell  and  uses  the 
bottom  screen  line  to  display  a  message  lor  each  ol  the  status  tonditions 
(except  "Suicessful  completion"'  tmd  "Current  form  incomplete")  listed  in 
Table  o  1.  Appendix  C  lists  the  messages.  Alter  displaying  a  debtig  mode 
message,  the  Firm  Driver  places  the  cursor  in  the  lower  right  corner  ol  the 
screen  until  you  press  the  KNTKK  or  RKIl'KN  ke\ .    j'his  jjioicss  prevents 
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your  profjram  liom  clearin^^  or  oservvritint^  a  debug  mode  message  before  you 
have  seen  it.  W'heti  you  press  the  K.\  TKR  or  HF/rrKN  key.  your  |)rogram 
resumes  and  can  then  use  the  KIH'TL  call  to  display  program-related  mes- 
sages on  the  bottom  screen  line. 

The  appropriate  error  code  is  returned  to  the  calling  program  except  for  status 
code  FKi$I)LN.  \alue     Ki  (data  specified  tor  output  too  long). 


5.1.3  The  Debug  Mode  and  Application  Programming 
Techniques 

Because  the  Form  I)ri\er  explicitly  signals  all  errors  with  calls  in  the  debug 
mode,  you  can  use  the  Form  Driver  to  fully  debug  your  program  (with  respect 
to  mistakes  with  the  Form  Driver*.  Therefore,  alter  debugging  a  program,  you 
ma\  choose  not  to  test  for  certain  errors  that  should  not  oci  ir  in  a  fully 
debugged  application,  such  as  an  incorrect  field  name  or  forin  name  or  an 
incorrect  number  ol  argument.-<  in  a  call. 

However,  some  errors  can  occur  e\en  in  a  tull\  debugged  program.  In  partic- 
ular, even  in  a  finished  FMS  program,  you  should  check  lor  1/0  errors  alter 
calls  that: 

•  Open  and  c'lose  a  form  library  file. 

•  Display  a  form  (and  must  therefore  read  a  form  library  file). 

•  Solicit  operator  responses. 

5.1.4  Signaling  the  Application  Operator  about  Program  Errors 

In  man\  cases.  FM.S  application  operators  cannot  be  expected  to  leai  <  much 
about  the  hardware  or  software  that  they  use.  With  respect  to  error  conditions 
that  are  not  total' v'  axoidable.  the  application  designer  and  programmer  are 
under  pressure  to  signal  the  problem  ai..'  its  solution  as  ilearly  as  p(»ssib'e. 
The  FPl'TL  call  is  especially  useful  for  giving  operators  and  their  .-upervisors 
the  messages  about  the  application  program  status  that  they  will  find  most 
Useful.  Isii'.g  as  an  example  a  lase  when  an  1  ()  erntr  may  occur,  the  following 
general  illustration  shows  one  wav  that  the  FITTL  cmII  can  be  used  with  the 


v% 


other  status    aid  error  i 


heck 


mi'  features: 


1.      Th'. 


program  enc(»unters  an 


I/O 


error  while  trying  to  displav  a  form. 


The  program  delect.s  the  error  by  usmg  (lie  F.S'I'.AT  call.    The  call  returns 
the  error  code     iH  for  an  error  in  reading  a  form  library  file. 


m- 


•  T    The  program  uses  the  status  code  as  an   index  into  a  list  of  progra 
sp'iilic  mes.sages  and  finds  the  follov.ing  message:  "Proper  fortn  not  axoil- 
able.  Contact  Ms.  .la(k>on." 

4.  i  U-  pr»»gram  uses  the  FIM  TL  call  to  display  the  message  on  the  !)ot.om 
screen  line.  The  program  then  imtnediatelv  u^es  a  call  for  an  operator 
response  (the  FdF/I"  cad)  to  i-n.sure  that  the  message  retnains  visible  unid 


the  operator  see>^    iiui  res|)onds  to  it. 

The  FIM    TL  I  all  i-  described  m  lull  in  Chapter  ti 
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5.2    The  Role  of  the  Field  Terminators 

The  field  terminators  dei'ine  one  ot  the  tollowinji  conditions: 

1.  When  the  operator  wants  to  work  on  the  next  lorm. 

2.  When  the  operator  wants  to  work  on  a  different  field  from  the  current 
field. 

Each  of  the  keys  listed  in  Table  5-1  controls  a  field  terminator.  The  Autotah 
field  attribute  also  controls  a  unique  terminator.  When  an  operator  presses  a 
key  or  completes  a  field  that  has  the  Autotah  attribute,  the  Form  Driver 
either  proce.sses  the  terminator  itself  and  displays  the  effect  for  the  operator  or 
returns  a  unique  field  terminator  code  to  your  program  and  leaves  the  choice 
ol  processes  to  the  program.  Table  ")--l2  also  lists  the  process  and  code  that  the 
Form  Driver  uses  tor  each  field  terminator  key. 

When  you  set  the  V'TKK)  keypad  to  the  alternate  keypad  mode,  the  P'orm 
Driver  also  treats  the  keypad's  numeric  keys,  comma  (  .  I  key.  hyphen  (  -  ) 
key.  and  decimal  point  (  .  I  key  as  field  terminators.  The  codes  lor  these 
alternate  keypad  mode  terminators  are  always  returned  to  yoiu'  program  im- 
mediately. 

This  section  describes  how  your  program  can  use  the  field  terminators  and 
Form  Driver  calls  to  guide  an  operator  through  the  fields  in  a  form  in  any 
order. 

5.2.1    Relationship  Between  the  Field  Terminators  and  Form 
Driver  Calls 

In  eifect.  the  Form  Driver  works  between  the  operator  and  the  application 
program  that  the  operator  is  using.  When  the  program  initiates  a  call  to  get  an 
operator  response,  the  Form  Driver  allows  the  operator  to  type  an  entry  in  a 
lield.  When  the  operator  presses  a  lield  terminator  key  that  completes  the 
call,  the  Form  Driver  passes  the  response  and  the  field  terminator  code  to  the 
program  and  prohibits  the  operator  from  lurther  typing. 

Only  the  lollowing  tour  Form  Driver  calls  allow  the  operator  to  res|)ond: 

•  FCiF/r.  to  ge*  the  value  lor  a  specified  field  and  the  field  terminator. 

•  FdKTAF.  to  get  the  value  lor  any  field  that  the  operator  choo.ses,  as  well  as 
the  field  name  and  the  field  terminator. 

•  FCiF/r.-XL.  to  get  i>  I'oncatenated  string  of  all  field  values  for  the  current  lorm 
and  the  last  field  terminator  used. 

•  FINTA'.  to  get  a  concatenated  string  of  the  field  values  from  the  current  line 
of  the  specified  scrolled  area  and  the  last  field  terminator  used. 

For  each  of  these  four  calls,  the  Form  Driver  validates  all  field  terminators. 
For  example,  with  the  cursor  in  the  first  field  in  a  lorm.  the  Form  Driver 
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accepts  the  field  terminator  lur  the  TAB  key  hut  does  not  accept  the  field 
terminator  for  the  HACKSi'ACK  key. 

Tahle  ")-;{  lists  the  four  calls  and  shows  the  field  terminator  keys  that  com- 
plete each  call.  The  KCIKT  call  leaves  total  control  of  responding  to  any  field 
terminator  to  the  program.  The  FGETAF  call  allows  the  operator  to  choose 
one  field  hut  returns  control  to  the  program  as  soon  as  the  operator  completes 
an  Autotab  field  or  modifies  a  field  and  presses  any  field  terminator  key.  The 
FCipyrAL  call  leaves  the  Form  Driver  in  control  of  responding  to  any  field 
terminator  except  when  the  operator  presses  the  ENTP'R  or  RETL'HX  key. 
The  FINLX  call  leaves  the  P'orm  Driver  in  control  within  a  line  of  a  scrolled 
area. 

For  a  general  illustration  of  the  flexibility  that  the  .set  of  field  terminator 
features  and  related  calls  gives  you.  compare  the  following  two  methods  of 
getting  all  ol  the  current  field  values  (rom  the  operator.  (The  illustrati  i 
assumes  that  none  of  the  fields  has  any  special  attributes,  such  as  the  Re- 
sponse Required  attribute.) 

1.     I'sing  the  FliHTAl,  call. 


•  The  program  initiates  the  FCiKTAL  call. 


th 


e  cursor  trom 


'I'he  operator  uses  the  field  terminator  keys  that  movi 

'sses  these  field  termina- 


tield  to  field  at  any  time.  The  Form  Dri\er  proce 
tors  without  returning  them  to  the  program. 


•  When  the  operator  presses  the  KXTER  or  RE:TURN  key.  the  Form 
Driver  returns  the  field  terminator  code  and  the  string  of  field  values  to 
the  program. 

•  The  program  then  is  in  control  of  what  the  operator  does  next. 
2.    I'sing  a  series  of  F(iK  T  calls 

•  The  program  initiates  the  FCiKT  call.  The  operator  can  only  type  and 
change  the  entry  in  the  specified  field. 

•  When  the  operator  presses  any  field  terminator  key.  the  Form  Driver 
returns  the  field  terminator  code  and  the  single  field  value  to  the  pro- 
gram. The  program  then  is  in  control  of  what  the  operator  does  next.  For 
example,  on  the  iiasis  of  the  field  value  or  the  field  terminator,  the 
program  can  specifv  the  same  field  or  another  field  in  the  next  F(1KT 
call. 
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Table  5-2:     Field  Terminator  Keys,  Codes,  and  Typical  P^ffects 


Key 


Code 

High  Level 

Languages       MACRO!  1 

(Decimal)  (Global) 


Usage  or  Meaning 


entp:r 
or  rp:turn 


u. 


Pr$NTR 


TAB 


FT$NXT 


• 


BACKSPACE 


FT$SNX 


FT$PRV 


Noiii' 
(Autotab) 

PF;< 

(Exit 
Scrolled 
Area 
Backward  I 


3. 


FTSSPI^ 

FTSATB 
FT$XBK 


'rcrmiiiates  all  entries  in  the  Ibrni.  II  the 
call  being  processed  is  an  FCiETAL  and 
required  entries  are  not  coiiii)lete,  the 
Form  Driver  retuses  to  accept  the  termi- 
nator, and  the  oi)erator  remains  in  con- 
trol. It  required  entries  are  complete, 
the  terminator  is  always  returned  to  the 
program.  Therelore.  the  linal  ef'lect  de- 
pends on  the  next  call  that  the  program 
initiates  tor  an  operator  response. 

It  any  other  call  is  being  processed,  only 
the  requirements  tor  the  current  field 
must  be  satisfied.  If  so,  control  is  re- 
turned to  the  program. 

\'alid  only  when  the  current  field  is  not 
the  last  field  in  the  forin  that  is  not  Dis- 
play Only.  Moves  the  cursor  to  the  ini- 
tial position  of  the  next  lield. 

Processed  by  the  Form  I)ri\er  for  the 
FCETAI,  and  FINLN  calls  and.  until 
an  entry  is  typed  or  modified,  tor  the 
FCETAF  call.  Returned  to  the  program 
for  the  F(;E'r  call  and.  alter  an  entry  is 
typed  or  modified,  the  FCETAF  call. 

Scroll  forward  to  the  next  field.  The 
TAB  key  terminated  ini)ut  in  last  field 
of  a  .scrolled  line.  .Always  n  rned  to  the 
program. 

\alid  only  when  the  current  field  is  not 
the  first  tield  in  the  form  that  is  not 
display  only.  Moves  the  cursor  to  the 
init.al  position  ot  the  previous  field. 

Processed  as  for  the   T.AB  key. 

Scroll  backward  to  tlu'  |)revious  field. 
The  BACKSPACE  key  terminated 
input  in  the  first  field  in  a  strolled  line. 
Always  returned  to  the  program. 

Processed  as  lor  the  TAB  kev. 


(Valid  in|)ut  onl\  when  the  current  field 
is  in  a  scrolled  area!  Movt's  the  cursor 
out  of  the  scrolled  area  to  the  itutial  |)o- 
sition  of  the  previous  field  that  the  oper- 
ator is  allowed  to  complete. 


(continued  on  next  pagel 
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Table  5-2  (C'ont.):     Field  Terminator  Keys,  Codes,  and  Typical  Effects 


Kev 


(^ode 


Usage  or  Meaning 


High  Level 
Languages 
(Decimal) 


MACRO  II 

(Global) 


I'R 

(Kxil 
Scrolled 
Area 
Forward) 

Dowiiarrow 

(SlToli 

P'orward) 


I  'parrow 
(Scroll 
Backward] 


FT$XFVV  (V'alid  inj)ut  only  when  the  current  field 

is  in  a  scrolled  area)  Moves  the  cursor 
out  ol  the  scrolled  area  to  the  initial  po- 
sition of  the  next  field  that  the  operator 
is  allowed  to  complete. 

FTSSFW  (\'alid  input  only  when  the  current  field 

is  in  a  scrolled  area).  The  scrolled  area 
is  scrolled  up  and  the  current  line  re- 
mains the  same  physical  line  (with  new 
data)  or  the  cursor  moves  down  one  line 
and  that  line  becomes  the  new  current 
line.  The  cursor  moves  to  the  initial  po- 
sition of  the  first  field  that  the  operator 
is  allowed  to  complete  in  the  current 
line. 

FTSSHK  (\'alid  input  only  when  the  current  field 

is  in  a  scrolled  area).  The  scrolled  area 
is  scrolled  down  and  the  current  line  re- 
mains the  same  physical  line  (with  new 
data)  or  the  cursor  moves  up  one  line 
and  that  line  becomes  the  new  current 
line.  The  cursor  moves  to  the  initial  po- 
sition of  the  first  field  that  the  operator 
is  allowed  to  complete  in  the  current 
line. 


Table  5-;i:    The  Relationship  Between  the  Calls  to  Get  Operator 
Responses  and  the  Field  Terminators 


tall  Field  Terminator  Keys  that  Complete  the  Call 

F(;F/!'  Any  valid  field  terminator  key  or  the  Autotab  code. 

FtJETAF  KNTKK,  RKTl'HN.  or  any  typed  tield  entry  followed  by  any  valid  field 

terminator  key  or  the  Autotab  code. 

FC.KTAL  KNTKK  or  HKTrHN. 

FINLN  .\u\  valid  Held  tcrnunator  key  or  the  Autotab  code. 


In  terms  ot designiiiK  forms  and  proj^rams  lor  FMS  applications,  the  following? 
priticiples  provide  a  uselul  sumni.    v  of 'I'ahks  5  2  and  5  H: 

1.  Kxeept  for  the  KN  TKH.  HF/rUKN.  PF;i  and  PF4  keys,  the  effects  of  the 
field  terminator  keys  cannot  he  changed  from  what  DKIITAL  has  de- 
sif^ned  in  the  following;  cases: 

•  For  the  FCiKTAL  call. 

•  For  the  FINLN  call. 

•  For  the  FCIKTAF  call  before  the  operator  makes  a  field  entry. 
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2.  When  the  operator  presses  the  ENTP:K.  RPTrURN,  FF.'l  or  PF4  key,  or,  in 
response  to  the  FOET  call,  any  field  terminator  key,  the  program  alone 
controls  the  etiect  that  the  operator  sees. 

For  example,  if  you  use  the  FOETAL  call  in  a  program,  the  TAB  key  will 
always  advance  the  cursor  from  field  to  field  according  to  the  default  order 
that  DIGITAL  has  implemented.  However,  if  you  use  a  series  of  FGET  calls 
instead  of  the  FGETAL  call,  the  program  is  passed  the  field  terminator  code 
for  the  TAB  key  and  can  react  to  it  in  any  way  you  specify.  For  example: 

You  can  use  the  FPFT  call.  After  the  operator  uses  any  field  terminator  that 
returns  control  to  the  application  program,  the  program  can  initiate  the  FPFT 
call,  in  effect  making  the  Form  Dri^'er  display  the  effects  of  any  field  termi- 
nator key.  In  the  example  of  an  FGE^T  call  terminated  by  pressing  the  TAB 
key,  the  program  can  react  by  specifying  the  BACKSPACE  key  code  in  the 
FPFT  call.  Then,  the  effect  of  the  next  FGET  call  would  be  to  move  the  cursor 
back  to  the  previous  field  in  the  form. 

Or  you  can  use  another  FOET  call.  Again  in  the  example  of  an  FGET  call 
terminated  by  pressing  the  TAB  key,  the  program  can  react  with  another 
F(iET  call  that  specifies  by  name  the  next  field  that  the  operator  is  to  com- 
plete, regardless  of  where  the  field  appears  on  the  operator's  screen. 


5.2.2    Using  the  Alternate  Keypad  Mode  Terminators 

Normally,  the  numeric  and  punctuation  keys  on  the  VTlOO  keypad  produce 
the  same  numbers  and  characters  that  the  corresponding  keyboard  keys  pro- 
duce. Therefore,  tor  many  common  applications  the  operator  can  enter  nu- 
meric data  by  using  the  keypad  rather  than  the  more  cumbersome  keyboard 
arrangement. 

For  special  applications,  you  can  set  the  V'TIOO  to  the  alternate  keypad  mode 
from  your  program  and  then  design  the  applications  to  use  the  numeric  and 
punctuation  keys  on  the  keypad  as  field  terminator  keys.  In  this  case,  the 
Form  Driver  always  passes  the  alternate  keypad  mode  terminators  to  the 
program  immediately,  regardless  of  whether  the  Input  Required  and  Must  Fill 
requirements  are  satisfied  for  the  form.  The  \'T1()()  I 'scr  (iiiidr  descrii)es  how 
to  set  the  alternate  keypad  mode.  Table  5  4  lists  the  keypad  keys  that  are 
affected  by  the  alternate  keypad  setting  and  the  code  that  is  returned  to  your 
program  for  each  key. 

In  each  case,  the  character  returned  is  the  last  character  in  the  escape  se- 
quence generated  by  the  key  in  alternate  keypad  mode. 
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Table  5-4:    Alternate  Keypad  Mode  Field  Terminator  Keys  and  Codes 


Keypad  Key 


Code  Returned 
Character  Value  (decimal) 


Comma  (  .  ) 
Hyphen  (  -  ) 

Decimal  (  .  I 
0 
1 
2 
3 
4 
5 
6 
7 
8 
9 


5.3   The  Impure  Area 


1    (lowercase    L)      108. 

m  109. 

n  110. 

p  112. 

q  113. 

r  114. 

s  li,3. 

t  116. 

u  117. 

V  118. 
w  119. 
X  120. 

V  121. 


The  size  of  the  impure  area  must  satisfy  the  requirements  of  the  largest  form 
that  you  are  using.  The  actual  size  also  depends  on  the  programming  language 
that  you  are  using  to:  your  application.  P'or  any  high  level  language,  create  an 
impure  area  that  is  64.  hytes  larger  than  the  impure  area  size  reported  hy  the 
Form  Editor  or  P'orm  Utility.  For  MAURO-ll,  you  do  not  need  to  add  the  64. 
hytes. 

NOTE 

Becau.sc  of  operating  system  factors,  a  form  desciption  on 
HSX  IIM  and  HSX  IIM  PLTS  systems  reipiircs  an  impure 
area  that  is  44.  hytes  larger  than  on  KT  11  .systems,  regardless 
of  the  language  u.sed  for  the  application.  On  KSX  llM  and 
KSXllM  PLUS  systems,  the  Form  Editor  and  Form  I'tility 
include  this  extra  requirement  when  they  report  the  impure 
area  size.  On  H'V  11  systems,  they  do  not  include  the  extra 
requirement. 

The  impure  area  is  u.sed  hy  the  Form  Driver  to  maintaiti  terminal  context 
hetween  calls.  U  vou  issue  direct  calls  from  your  program  to  display  data  on  or 
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solicit  input  from  the  terminal,  rather  than  usinjj  the  Form  Driver  tor  all 
terminal  I/O.  the  results  of  the  next  ^^)rm  Driver  call  may  not  be  as  expected. 

5.4    Task  Buiiding  Programs  with  Memory  Resident  Forms 

Memory  resident  forms  are  easily  created  and  included  in  your  FMS  applica- 
tion. Use  the  Form  Utility  to  create  object  modules  of  the  forms  you  wish  to 
include  in  your  program  as  in  the  foUowinfj  example. 

■'F  U  T    F  0  ry  M  ^  .  n  p  I  =  n  F  M !   T  B  ,  r  i  R    n  p 

DM0:  C30  .lODDEMLIB  .FLB  ;  1  Form  name''  PAlVTSfREt 
DM0:  C30  .10]DEhLIB  .FL5  ;  1  Form  name''  FIRST'Sft; 
DM0  :  [30  .  lODDEML  IB  .  FLB  ;     Form    name'    jiET; 


if? 


Both  form  descriptions  are  included  in  the  mt)dule  FORMS. OBJ.  If  you  wish, 
forms  may  be  put  in  separate  files. 

When  your  application  is  task  built  with  memory  resident  forms,  the 
FDV'DAT  module  ot  the  Form  Driver  must  be  referenced  before  an\'  of  the 
memory  resident  forms.  This  is  done  by  including  the  Form  Driver  library 
with  an  explicit  reference  to  FDV'DAT  in  the  Task  Builder  corr.  \nd  se- 
quence before  any  of  the  files  containing  forms.  The  following  example  illus- 
trates this. 


TKBv  FQRDEM  .FORDEM/ -SP  =  FORDEM 

TKB-  HLLFOR  .FDOLIB' LB:FD'.'DAT  .FDOLIB  LE 

TKB  FORMS 

TKB  >  LB: [ 1   ,1  ]FORQTS/LB 

TKB.:-  // 

On  IAS  you  can  omit  the  fourth  line  in  the  example  above  if  you  included 
FOROTS  in  SYSLIB  when  you  installed  ywur  FORTRAN  software. 

5.5    FCS  and  RMS  System  Support 

Two  versions  of  the  Form  Driver  are  supplied  as  object  libraries: 

•  FDVLIB.OLB  -  the  Form  Driver  library  for  FCS  I/O  support. 

•  FDVLRM.OLB  -  the  Form  Driver  library  for  RMS  I/O  support. 

The  choice  you  make  depends  on  the  programming  langu'ig':'  you  u.se  for  your 
application  as  well  as  the  overall  design  of  the  application.  Regarding  the 
design,  make  your  choice  on  the  basis  of  your  experience  with  and  knowledge 
of  t'  "  F(\S  and  RMS  systems.  Regarding  the  relationship  between  the  pro- 
gramming languages  and  the  two  systems.  Table  5  5  summarizes  the  Form 
Driver  rea''.'rements. 


I 
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Table  5-5:    FCS  and  RMS  System  Requirements  for  the  Form  Driver 


Lan^^uage 


Requirements  for 
FCS  Support  RMS  Support 


BASIC-  I'LIS  2 
PDF  11  (X)B()L 
FORTH  AN  I\ 
FORTRAN  IV  PIA  S 
MACHO  11 


None. 

He(|uireci 

None. 

Hei)uired 

Reciuired. 

Noiu', 

Oi)ti()iial. 

Optional, 

Optional. 

0|)tional. 

5.6    Using  the  Form  Driver  As  a  Resident  Library  with  FCS 
Support 

The  command  file  FDVRES.CMD  builds  the  Form  Driver  as  a  resident  li- 
brary with  FCS  support.  This  command  tile  can  be  modified  to  include  addi- 
tional routines,  such  as  a  high  level  language  interface,  in  the  library. 

5.6.1    Procedure  for  RSX-11M  and  RSX-11M-PLUS 

To  use  the  Form  Driver  as  a  resident  library,  you  must  allocate  a  partition 
named  FDVRES  and  then  install  the  resident  library  when  you  build  your 
application  system. 

The  following  command  to  VMR  allocates  the  partition: 

SET    /MAIN:^FDVRFS:*:anM:COM 


The  partition  size,  here  41)0.  must  be  adjusted  for  any  additional  modules 
added  to  the  Form  Driver. 

*,  the  base  address  of  the  partition,  is  here  spc;'ified  in  the  format  of  RSX 
VH.2  VMR.  As  a  command  to  MCTi.  the  address  must  be  specified  as  a 
number. 

Details  on  the  allocation  of  partitions  can  be  found  iti  the  (Operator's  I^rocc- 
durcs  XUinudl  under  the  SHT  ctmimand  and  in  the  S)  S(iK.\  Manual  in  the 
section  describing  VMR. 

When  you  build  your  application  system,  a  privileged  user  can  use  the  follow- 
ing MCR  command  to  instftll  the  r«  sident  library  from  I'K"  [.'lO.  10): 

INSTALL.     r30  ,  lOjFD'.TyES 

To  replace  a  resident  lil;rary,  install  a  Jiew  copy. 

The  Form  Driver  cannot  be  built  as  a  resident  library  with  RMS  support. 

An  example  of  a  Task  Builder  c(»mniand  procedure  to  l)uild  a  progratn  with 
resident  lil)rary  sup|)ort  follows: 
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TASK  .  TASK  =  TASK  .  [ 30  ,  1  0  ]  FDUDRS 

/ 

RESLIB= [30  .  lOJFDORES/RD 

PAR  =  FDORES:  100000 : 0 

// 


The  base  of  the  PAR  option  must  agree  with  the  base  given  in  the  PAR  option 
in  the  FDVTKB  command  file.  The  Form  Driver  is  not  PIC  (position  inde- 
pendent code).  See  Chapter  7  of  the  Task  Building  Reference  Manual  for 
more  details  on  building  and  using  resident  libraries. 


5.6.2    Procedure  for  IAS 

The  command  file  FRSTKB.CMD  builds  FDV  as  a  resident  library  SGA.  The 
command  file  specifies  the  base  address  for  FDVRES  as  16K.  You  can  change 
this  if  necessary.  Note  that  FDVRES  is  not  position  independent.  You  can 
modify  FRSTKB.CMD  to  include  in  the  library  additional  routines,  such  as 
high-level  language  interfaces. 

To  install  the  resident  library  SGA.  use  the  MCR  INS  or  the  PDS  INSTALL 
command  as  follows: 


MCR: INS  FDORES/LI 


or 


PDS  INSTALL/L  IBRARY  FDORES 

To  remove  a  res.dent  library  SGA.  use  the  MCR  command  REM  with  the 
/LI  switch  or  the  PDS  command  REMOUE/L  I  BRARY. 

See  the  IAS  MCR  I  'ser's  Guide  or  the  IAS  PDS  User's  Guide  for  details  of  the 
commands. 

The  Form  Driver  cannot  be  built  as  a  resident  library  with  RMS  support. 

An  example  of  a  Task  Builder  command  procedure  to  build  a  task  using 
FDVRES  is  as  follows: 

TKB>TASK  .MAP=  IM  .  IN2 

Th3  > 

ENTER  OPTIONS: 

TKB  5GA=FD0RES:R0 

TKB,  ,  / 


or 


PDS  ^     LINK /TASK  :  TASM  /  MAP /OPT  I  ONS 
FILE'     :n1  .IN2 
GPTIGNS'^    SGA-FDORES:RO 
nPTIGNS"'     / 


See  Chapter  8  of  the  IAS  Task  Huilder  Reference  Manual  for  more  details  on 
building  and  using  resident  library  SGAs. 
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5.7   The  High  Level  Language  Interface 

A  special  component  of  the  Form  Driver,  called  the  high-level  language  inter- 
face, processes  your  high-level  language  Form  Driver  calls.  The  interface 
passes  the  values  that  you  supply  to  the  Form  Driver  and  returns  values  to 
your  program  from  the  Form  Driver. 

The  high-level  language  interface  is  entirely  transparent  to  you  and  to  your 
program  except  when  you  build  your  FMS  application.  To  use  forms,  you 
need  to  use  only  the  Form  Driver  calls.  However,  as  part  of  the  procedure  for 
building  a  running  application,  you  must  link  the  proper  high-level  language 
interface  component  with  the  Form  Driver  and  your  program.  The  details  for 
building  applications  in  each  language  are  described  later  in  this  chapter. 

Most  of  the  mutual  requirements  for  the  Form  Driver  and  each  high-level 
language  are  the  same.  They  are  grouped  in  the  following  four  categories  and 
described  in  the  sections  that  follow: 

1.  The  input  and  output  arguments  for  the  Form  Driver  calls. 

2.  The  syntax  of  the  calls  and  conventions  used  in  this  manual  to  define  the 
syntax  for  the  different  languages. 

3.  The  completion  status  of  calls  for  success  and  failure. 

4.  Interpretation  of  the  field  terminators  that  an  operator  uses  while  working 
with  your  application  and  using  the  terminators  flexibly. 

5.7.1    General  Description  of  the  Arguments 

Collectively,  the  high-level  language  calls  use  arguments  to  pass  values  to  the 
Form  Driver  and  to  receive  values  that  the  Form  Driver  returns.  For  each  call, 
this  manual  uses  the  term  Input  Arguments  (or  Inputs)  to  refer  to  the  argu- 
ments that  pass  values  from  your  program  to  the  Form  Driver.  The  term 
Output  Arguments  (or  Outputs)  refers  to  the  arguments  for  values  that  the 
Form  Driver  returns  to  your  program.  For  example,  the  FGET  call  allows  an 
operator  to  enter  data  in  a  field  and  then  returns  the  field  value  to  the 
program  when  the  operator  finishes.  The  input  arguments  for  the  FGET  call 
are  the  field  name  and,  if  the  field  is  indexed,  the  field  index.  The  output 
arguments  for  the  FGF^T  call  are  the  field  value  when  the  operator  terminated 
the  field  and  the  code  for  the  field  terminator. 

Table  5-6  shows  the  abbreviations  that  this  manual  uses  for  all  of  the  Foim 
Driver  call  arguments  and  describes  brielly  the  requirements  or  value  for  each 
input  argument  and  output  argument.  (In  Section  5.11,  Table  5-16  is  a  simi- 
lar list  for  MACRO- 11.) 

The  full  descriptions  of  the  Form  Driver  calls  in  Chapter  6  also  use  the  abbre- 
viations that  appear  in  Table  5-6. 
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Table  5-6:     Summary  of  Form  Driver  Inputs  and  Outputs  in  High  Level 
Language  Calls 

^^                                                        High-Level  Language 

Argument  Abbreviation 

Requirement  or  Value 

Inputs 

CHAN 

A  channel  number  for  a  form  library  file. 

FID 

A  field  name  or  a  named  data  label,  6  characters  lonfj, 
including  padding  (for  FORTRAN  IV  and  FORTRAN 
IV-PLUS.    add   a    NULL   byte   also).    To   specify   a 
scrolled  area,  use  the  name  of  any  field  in  the  scrolled 
area. 

FIDX 

A  field  index  for  the  specified  field  (when  the  field  is 
indexed)  or  the  index  for  a  named  data  value.  The 
argument  is  ignored  unless  the  Form  Driver  is  process- 
ing an  indexed  field  or  accessing  named  data  by  index. 

^^                                                                  FLNM 

A  form  library  file  specification. 

FNAME 

A  form  name,  6  characters  long,  including  padding  (for 
FORTRAN  IV  and  FORTRAN  IV-PLUS,  add  a  NULL 
byte  also). 

FVAL 

• 

As  an  input  value,  the  single  value  or  the  concatenated 
values  to  be  displayed: 

•  in  a  field. 

•  in  the  top,   bottom,  or  current  line  of  a  scrolled 
area. 

•  in  the  last  line  of  the 
screen. 

•  in  an  entire  form. 

IMPURE 

The  name  of  a  subscripted  variable  (or  array)  of  bytes 
for  the  impure  area. 

LINE 
^^                                                                   SIZE 

The  explicit  starting  line  number  for  the  form,  overrid- 
ing the  line  number  assigned  with  the  Form  Editor. 
The  size  of  the  impure  area  in  bytes. 

^B                                                                  TERM 

As  an  input  value,  the  numeric  code  for  the  terminator 
that  the  Form  Driver  is  to  process. 

Outputs 

(The  status  code  is  set  for  all  calls.] 

FID 

The  current  field  name  or  a  named  data  label. 

FIDX 

A  field  index. 

FLEN 

The  length  of  a  specified  field  (not  the  length  of  the 
data  the  field  contains). 

FVAL 

• 

A  named  data  value,  a  single  field  value,  or  a  conca- 
tenated string  that  is  composed  of  several  field  values 
(includmg  padding  when  a  value  is  shorter  than  its 
field). 

(continued  on  next  page) 
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Table  5-6  (Cont.):    Summary  of  Form  Driver  Inputs  and  Outputs  in  High 

Level  Language  Calls 


Hi^h-Level  Language 
Argument  Abbreviation 


TERM 


STATUS 


STAT2 


Requirement  or  Value 


The  numeric  code  for  the  key  that  the  operator  used  to 
terminate  input: 

•  in  a  field. 

•  in  a  line  in  a  scrolled 
area. 

•  in  an  entire  form. 

A  numeric  code  for  the  completion  status  of  the  last 
call  that  was  executed. 

A  numeric  RMS  or  FCS  status  code  for  detailed  infor- 
mation when  the  STATUS  value  is  -4  or  -18. 


As  shown  in  Table  5-6,  the  maximum  length  of  form  names  and  field  names  is 
six  characters.  For  FMS  applications  in  the  high-level  languages  except  FOR- 
TRAN IV,  the  Form  Driver  pads  form  and  field  names  that  are  shorter  than 
six  characters  with  spaces.  Form  and  field  names  that  are  longer  than  six 
characters  are  truncated  when  passed  to  the  Form  Driver.  The  field  names 
that  the  Form  Driver  returns  are  six  characters  long,  including  any  spaces 
that  have  been  added. 

5.7.1.1  Argument  Data  Types  —  The  data  types  of  the  Form  Driver  argu- 
ments depend  on  the  language  that  you  are  using.  Therefore,  specific  require- 
ments are  listed  later  in  this  chapter  in  the  sections  that  provide  information 
that  is  specific  to  the  languages. 

The  general  data  types  that  the  Form  Driver  uses  regularly  are  integers  and 
alphanumeric  strings.  Examples  of  arguments  that  pass  integer  values  to  and 
from  the  Form  Driver  are  the  arguments  for: 

•  The  starting  line  number  for  a  form. 

•  The  code  for  the  key  that  an  operator  uses  to  finish  a  field. 

•  The  size  of  the  impure  area. 

Examples  of  arguments  that  pass  alphanumeric  strings  to  and  from  the  Form 
Driver  are  the  arguments  for: 

•  The  name  of  a  field. 

•  A  named  data  value. 

•  A  value  to  be  displayed  in  a  field. 

5.7.1.2  The  Relationship  Between  Field  Lengths  and  Values  —  Regardless  of 
the  practical  purposes  of  the  fields  in  a  form,  the  Form  Driver  always  treats 
field  values  as  strings.  For  example,  when  the  Form  Driver  returns  a  field 
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value  to  your  program  as  an  argument  to  the  FGET  call,  your  program  re- 
ceives a  string  of  characters  that  is  exactly  as  long  as  the  field  that  you 
specified.  (Except  for  FORTRAN  IV  and  FORTRAN  IV-PLUS,  in  which  case 
the  data  is  one  byte  longer  because  it  is  terminated  with  a  NULL  byte).  If  the 
value  is  shorter  than  the  field,  Fill  Characters  (either  zeroes  or  spaces,  as 
assigned  with  the  Form  Editor)  are  added. 

As  another  example  of  the  relationship  between  field  lengths  and  values,  when 
you  use  the  FPUTAL  call  to  display  specified  values  in  the  first  three  fields  of 
a  form,  you  pass  to  the  Form  Driver  a  concatenated  string  of  the  three  field 
values.  For  any  value  that  is  shorter  than  the  field  in  which  it  is  to  be  dis- 
played, you  add  Fill  Characters  so  that  the  value  and  the  field  are  the  same 
length. 

5.7.2    General  Description  of  Call  Syntax  for  High  Level 
Languages 

The  syntax  of  the  Form  Driver  calls  follows  the  requirements  and  conventions 
of  the  language  that  you  use.  BASIC-PLUS-2.  COBOL-11,  FORTRAN  IV, 
and  FORTRAN  IV-PLUS  calls  all  use  the  CALL  statement.  In  this  manual, 
only  the  call  statement  forms  are  listed  in  the  detailed  descriptions  of  the 
calls.  For  example,  the  CALL  statement  syntax  for  the  calls  to  get  a  field 
value  from  the  operator  and  then  display  a  message  on  the  last  line  of  the 
operator's  screen  is  as  follows: 

L    For  BASIC  "T,US-2,  FORTRAN  IV,  and  FORTRAN  IV-PLUS  - 

CALL  FGET.,         '  "-mjidlfidx]) 
CALL  FPUJL(fral, 

2.    For  COBOL-11  — 

CALL   "FGET"   USING  BY  DESCrvIPTOR  fval.  BY  REFERENCE  term. 

BY  DESCRIPTOR  fid  |.BY  REFERENCE  fidx]. 

CALL    "FPUTL"   USING  BY  DESCRIPTOR  fcal. 

The  argument  abbreviations  that  are  printed  in  lowercase  letters  stand  for 
arguments  that  you  must  provide.  They  must  be  in  the  order  shown  for  each 
call  and  must  meet  the  functional  requirements  described  in  Table  5-5. 

In  the  call  descriptions  in  this  manual,  square  brackets  (  [  and  1  )  enclose 
optional  arguments.  For  example,  in  the  FGET  call  illustrated  above,  the 
argument  for  a  field  index  (fidx)  is  required  only  to  specify  a  particular  field 
that  is  in  an  indexed  field. 

For  calls  that  have  more  than  one  optional  field,  omitting  one  requires  you  to 
omit  the  others  to  its  right.  For  example,  if  you  omit  the  optional  field  name 
argument  {fid)  in  the  following  call,  you  mu.st  also  omit  the  field  value  argu- 
ment ifial). 
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CALL  FPF Ktcrmlfidlfval]]) 

CALL   "FPFT"  USING  termlQ\'  DESCR  I  PTOR  /■/d  [Jral]]. 

For  some  calls,  you  can  omit  the  entire  list  of  ar^juments.  Fo*-  added  clarity  in 
this  manual,  these  call>  are  listed  both  with  and  without  the  argument  lists. 
For  example,  the  full  syntax  of  the  FFl'TAL  call  is  shown  as  follows: 

CALL  FPUTALr/raO 

CALL  FPUTAL 

The  Form  Driver's  high-level  language  interface  does  not  support  null  argu- 
ment lists  in  calls.  Tsing  the  second  form  of  the  FPl'TAL  call  above  as  an 
example,  the  following  form  is  invalid  at  all  times  within  an  FMS  application: 


CALL  FPUTALI ) 


IThe  null  argument  form  is 
lalwavs  invalid  with  FMS. 


With  FORTRAN  IV  and  FORTRAN  IV  FIA'S.  you  can  also  use  the  standard 
syntax  for  calling  a  function  subprogram.  The  function  subprogram  syntax  tor 
the  FCipyr  and  FIH'TL  calls  is  ifncLul  stands  for  the  value  ot  the  function): 

fncral  =    F(1EJ  (fraljrrm,fid[,fidx\) 

fncvnl  --    FPUTLr/ro/j 

When  you  use  a  Form  Driver  call  as  a  function,  the  value  of  the  function  is  the 
P'orm  Driver  completion  status  for  the  call.  Section  ').!  explains  status  and 
error  checking  in  more  detail. 

5.7.3    Status  and  Error  Checking 

As  rlescribcd  fully  in  Section  6.24.  the  F(»rm  Driver  includes  a  specific  call,  the 
FSTAT  ca!',  th"t  returns  status  codes  for  the  completion  status  of  the  last  call 
that  was  proces.sed.  Table  5-1  lists  the  status  coles  and  their  meanings. 


J 


• 


I 


5.8    The  Interface  for  BASIC-PLUS-2 

In  BASIC-PIA'S  2  applications,  all  numeric  values  pas.sed  to  and  from  the 
Form  Driver  must  be  integer  variables  or  constants.  String  values  must  also 
be  string  variables  or  constants.  When  the  Form  Driver  returns  a  string  value, 
the  length  is  the  length  of  the  field,  including  any  trailing  spaces  or  fill 
characters.  String  values  that  are  shitrter  than  the  BASIC  PMS  2  variables 
to  which  they  are  assigned  are  left  justified  and  the  fields  are  blank  filled. 
String  values  that  are  longer  than  the  variables  to  which  they  are  assigned  are 
truncated  and  cause  the  Form  Driver  to  set  the  status  code  to    22. 

BASI('-PLrS-2  programs  should  u.se  RMS  support. 

To  avoid  loss  of  typeahead  on  RSX  llM  and  RSX  llM  PLl'S.  FMS  appli- 
cations must  attach  the  terminal.  This  is  done  by  calling  the  subroutine 
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"WTQIO",  the  queue  I/O  request  and  wait  call  (see  the  description  ofQIOWS 
in  the  RSX-1 IM  Executive  Manual).  The  arguments  are  the  same  as  for  the 
FORTRAN  form  of  the  call:  INUM  is  768  and  LUN  is  the  LUN  assigned  to 
the  terminal  for  the  Form  Driver,  as  shown  in  the  following  example. 

CALL  WT3I0    (7G87,  ,'57,  ,51) 


e 


5.8.1    Arguments  for  the  Calls 

Table  5-7  lists  typical  BASIC-PLUS-2  data  types  and  data  structures  for 
each  of  the  arguments  in  the  Form  Driver  calls. 

Table  5-7:    Typical  BASIC-PLUS-2  Data  Types  for  Form  Driver  Argu- 
ments 


Argument 
Abbreviation 


Purpose,  Data  Type,  and  Data  Structure 


CHAN 

FID 

FIDX 

FLEN 

FLNM 

FNAME 
FVAL 

IMPl'RE 

LINE 

SIZE 

STATl'S 

SIAT'J 

TERM 


Channel      miber:  integer  variable  or  lonstanl. 

Field  name:  ()-bvte  string  variable  or  constant. 

Field  and  named  data  index:  integer  variable  or  constant. 

P'ield  length:  integer  variable  or  constant. 

Form  library  file  specification;  string  variable  or  constant  (the  size 
depends  on  application  requirements  and  conventions). 

Form  name:  (vtnle  string  variable  or  constant. 

Named  data  value,  one  or  mt)re  field  values,  text  for  display  on  the 
bottom  screen  line:  string  variable  or  constant  (the  size  depends  on 
the  application) 

Impure  area:  byte  array  (using  the  impure  area  size  that  the  Form 
Editor  and  Form  I'tility  report,  the  size  ot  the  array  should  be  (i4. 
bytes  larger  than  the  largest  impure  area  tor  the  forms  that  the 
application  u.ses). 

Starting  line  number  for  a  displayed  form:  integer  variable  or  con- 
stant. 

The  size  of  the  impure  area  in  bytes. 

Call  completitm  status:  integer  variable. 

FCS  or  KMS  .s\stem  error  code:  integer  variable. 

Field  terminator  code:  integer  variable  (..  ((mstant. 


5.8.2    Syntax  for  the  Calls 

All  of  (he  Form  Driver  calls  uso  the  CALL  statement.  Table  5-8  summarizes 
the  principal  purposes  and  shows  the  full  CALL  statement  syntax  for  each 
call.  The  arguments  that  you  must  supply  are  in  lowerca.se  letters,  and  op- 
tional arguments  are  enclosed  in  square  brackets  (  1  and  1  ).  The  forms  of 
calls  that  have  no  arguments  are  listed  separately.  The  argument  abbrevia- 
tions and  purposes  are  fully  described  in  Table  5  7. 
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Table  5-8:    Listing  of  BASlC-PLUS-2  Form  Driver  Calls 


Call 
Abbreviation 


FCLRSH 


FGCF 


FGET 


FGETAF 


FGETAL 


FIDATA 


FINIT 


FINLN 


FLCHAN 


FLCLOS 


FLKN 


Summary  and  Forms 


Clears  the  entire  screen  and  displays  the  form  with  the  default  field 
values.  If  a  line  number  is  specified,  uses  it  as  the  starting  line 
number  for  the  form. 

The  form  is:  CALL  F CLRSHffnamlJine]) 

Returns  the  field  name  from  the  P'orm  Driver  argument  list  (and  if 
it  is  an  indexed  field,  its  index). 

The  form  is:  CALL  F  GCFffidlfidx]) 

If  a  field  name  is  specified,  gets  and  returns  the  value  for  the  field 
and  the  field  terminato:-  used.  If  no  field  name  is  specified,  places 
the  cursor  at  the  lower  right  corner  of  the  screen  and  deactivates  all 
operator  responses  except  the  Return  and  Enter  keys. 

The  forms  are:LALL   FQEJ  (ft  al. term, fidlfidx]) 

CALL   FGET 

(iets  and  returns  the  value,  field  name  land,  if  the  field  is  indexed, 
its  index),  and  the  field  terminator  u.sed  for  the  field  that  the 
operator  chooses. 

The  form  is:  CALL  FQEl i\F(frnl. term. fidifidx]) 

If  the  call  includes  an  argument,  gets  and  returns  a  concatenated 
string  of  all  field  values  (and  optionally  the  last  field  terminator 
used).  If  no  arguments  are  specified,  gets  all  values  from  the  oper- 
ator but  only  stores  them  in  the  impure  area. 

The  forms  are:  CALL  FQElnLffcallterm]) 
CALL   FGETAL 

Gets  and  returns  the  named  data  value  that  has  the  specified 
index. 

The  form  is:  CALL  F  I  DATAC/i'd.v./ra/) 

Supplies  to  the  Form  Driver  the  name  of  the  impure  area  to  use 
and  its  size. 

The  form  is:  CALL  f  lUlldmpurc.sizrl.status]) 

Get."^  and  returns  a  concatenated  string  of  the  field  values  for  the 
current  line  of  the  scrolled  area  that  contains  the  specified  field 
name  and  the  last  terminator  used. 

The  form  is:  CALL  F  IW.UIfid.fvnI.term) 

Supplies  to  the  Form  Driver  the  I O  channel  (i-r\)  to  use  for 
reading  a  lorm  library  file. 

The  form  is:  CALL  F  LCHANrc/j(n!) 

Closes  the  current  form  library  file. 

The  form  is:  CALL   FLCLOS 

Returns  the  length  ol  the  specified  field. 

The  lorm  is:  CALL  fL£U(flen,fid{.fidx]) 

(continued  on  next  page) 
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Table  5-8  (Cont.):     Listing  of  BASK -PLUS-2  Form  Driver  Calls 


Call 
Abbreviation 


FLOPKN 


FN DATA 


FOUTLN 


FPFT 


Kl'ir 


Fl'lTAL 


FPITL 


KHKTAL 


FKKi'N 


FSHOW 


vSummary  and  Forms 


Opens  the  specified  form  library  file. 
The  fi)rm  is:  CALL  FLOP£N(flnm) 

(iets  and  returns  the  named  data  value  that  has  the  named  data 
label  specified. 

The  form  is:  CALL  FNDiAT P( fid. fvol) 

Displays  the  specified  string  of  field  values  in  the  current  line  of 
the  scrolled  area  that  contains  the  specified  field. 

The  form  is:  CALL  FnUTLNfM/ro/i 

if  the  call  includes  an  argument,  processes  the  specified  field  ter- 
minator and  identifies  the  appropriate  field  as  the  current  field.  To 
get  the  name  of  the  field,  use  the  FdCF  call.)  If  the  specified 
terminator  is  a  scrolled  area  terminator,  the  name  of  a  field  in  the 
intended  scrolled  area  must  be  specified,  and  if  a  string  j)f  values  is 
specified,  they  will  he  displayed  cm  the  top  or  bottom  line  of  the 
scrolled  area  after  the  terminator  is  processed.  If  no  argument  is 
included,  the  call  processes  the  last  terminator  that  was  used. 

The  forms  are:  CALL  FPF T(trrm\.fid\.fval]]) 
CALL  FPFT 

Displays  the  specified  value  in  the  specified  field. 
The  form  is:  CALL  F PUKfval.fidi.fidx]) 

Displays  values  in  all  fields  of  the  form.  If  a  concatenated  string  of 
values  is  supplied,  each  value  must  be  the  same  length  as  the  field 
in  which  it  is  to  be  displayed  and  the  values  mu.st  be  in  the  same 
order  that  the  FdKTAL  call  would  produce  for  the  form.  Values 
from  the  string  supplied  are  displayed  in  the  first  fields  of  the  form, 
and  defaults  are  disi)layed  in  any  field  that  remain.  If  no  string  of 
values  is  supplied,  default  values  are  displayed  in  all  fields. 

The  forms  are:  CALL  FPUT ALf/co/j 
CALL   FPUTAL 

If  an  argument  is  specified,  displays  the  specified  string  on  the 
bottom  line  of  the  screen.  It  no  argument  is  specified,  clears  the 
bottom  line. 

The  lorms  are:  CAL  L  FPUJL(fval) 
TALL   FPUTI 

Returns  the  current  values  lor  all  fields  in  the  form  in  the  same 
«)rder  that  the  FdhyrAK  call  would  produce. 

'i'he  form  is:  CALL   FRETAL  ^/'if//) 

Keturns  the  current  value  of  the  specified  field. 

The  form  is:  CALL  FryETr^lC/rfj/.//(/|./jri.vU 

Ch-ars  the  part  of  the  screen  thai  the  specified  form  recpiires  and 
displays  the  form  with  default  field  values.  It  a  line  number  is 
specified,  uses  it  as  the  starling  line  number  lor  the  form. 


The  form  is:  CALL  FSHO\A( fnamUinc]) 


(continued  on  next  page) 
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Table  5-8  (Cont.):    Listing  of  BASIC-PLUS-2  Form  Driver  Calls 


Call 
Abbreviation 


FSPOFF 


FSPO\ 


FSTAT 


Summary  and  Forms 


Turns  off  the  Supervisor  Only  mode  and  allows  the  operator  to 
enter  and  change  data  in  fields  to  which  the  Sujjervisor  Only  at- 
tribute was  assigned  with  the  Form  Kditor. 

The  form  is:  CALL  FSPOFF 

Turns  on  the  Supervisor  Only  mode  and  prevents  the  operator  from 
entering  or  changing  data  in  fields  to  which  the  Supervisor  Only 
was  assigned  with  the  Form  Editor. 

The  form  is:  CALL  FSPON 

Returns  the  status  code  for  the  last  call  that  was  processed  as  the 
value  of  the  first  argument.  The  value  of  the  second  argument  is 
meaningful  as  an  FCS  or  RMS  system  error  code  (depending  on  the 
version  ol'  the  Form  Driver  in  use)  only  il  the  value  of  the  first 
argument  is  -4  or  -18.  indicating  an  error  while  trying  to  open  or 
read  a  form  library  file. 

The  form  is:  CALL  FSl (^J(stntusl.stat2]) 


5.8.3    Building  a  BASIC-PLUS-2  Task 

Building  BASIC-PLUS-2  tasks  involves  editirr  .he  command  and  ODL  files 
produced  by  BASIC-PLUS-2. 

For  RSX-UM/M-PLUS: 


5BASDEM.CMD 

■ 

?  Command  file  to  h u  i  1  d  BASIC-PLU5-2  Demo 

« 

5  Underlined  items  are  c  h  a  ri  3  e  s  from  file  t'  m  i  1  t  with 

!  BASIC-PLUS-2  BUILD  command. 

; 

BASDEM/CP»BASDEM/-SP=BASDEM/MP 

;         A,j,j  ,„ap  file  if  desired. 

» 


I 
I 

I 


UNITS  =  1-11 

ASG  =  TI  :  n:5 

5  --    AssiSn  LUN  5  as  terminal. 

ASG  =  SY:6:7:8:9: 10: 11 : 12 

i        -   R  e  m  0  M  e  L  U  N  5  from  this  line. 

// 

I 

5BASDEM.QDL 

i 

I  TKB  Querlav  Description  File  for  BASIC-2  Demo 

J 

? 

J  U  n  ij  e  r  1  1  n  e  d  items  are  c  h  a  ri  s  e  s  from  file  t'  u  i  1  t  bv 

\  BASIC+2  BUILD  command. 

I 

.rvOOT  BirvOTl -USER  .RMS 

USER:  .FCTR  S Y  :  BASDEM- L I  BR -FORM 

'  •         Add  FMS  factor  to  root 


I 
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L  I  B  R  :   .  F  C  T  R  L  B  :  [  1  .  1]  B  A  S  I  C  2  . '  L  B 
! 
FORM:   ,FCTR  HLLBP2-FRM1 

; Add  HLL  Interface 

FRMl:   .FCTR  :■  DVLRM  /  LB  -  LB  :  L  1  .  1  1  RMSL  I  B  /  LB  :  PMSS  VM 


Add  FDV  and  define  RMS 
5  y  III  b  (  1  s 


RMS:    .FCTR  B I  DO  17 
@LB: [1.1 IBASICl 
.END 

For  IAS: 


BASDEM.CMD 

Command  file  to  build  BASIC- PLUS -2  Demo 

U  n  ij  e  r  1  1  n  e  d  items  are  c  h  a  ri  a  e  s  fro  m  file  built 
wits  BASIC-PLUS-2  BUILD  command. 

[11  .1 lb]BASDEM  .[  1  1  1  .  1  1G]BASDEM/-SP=[  1 1  .  1  1  G ] B ASDEM / MP 

;  A,j,j  rtiap  file  if  desire  ^j. 


UNITS  =  in 

ASG  =  TI  :  13:5 

i  --   Assign  LUN  5  as  terminal  for  FDU  . 

ASG  =     SY :G:7:8:3: 10:  1  1  :  12 

i  -  ReiTtoue     LUN    5     from     this     line. 

EMTTSK  =  2^88 


;basdem.odl 


USER 


LI  BR: 


FORM: 


TKB  Ouerlav  Description  File  for  BASIC-PLUS-2  Demo 


Underlined  items  are  changes  from  file  [>  u  i  1  t  b '/ 
BASIC-PLUS-2  BUILD  command. 

.ROOT  BASIC2-RMSR0T-USER.RMSALL 
.FCTR  SY:[11  ,11G]BASDEM-LIBR-F0RM 

Add  F  M  S  factor  to  root 


FRMl  : 

,_ _ 

• 

@LB: [1.1 ]BP2IC1 
@LB  :  [  1  .  1  ]RMS1  IS 
.END 


.FCTR  LB:  [ 1  .  1  ]BASIC2/LB 
.FCTR  [ 11  .11G]HLLBP2-FRM1 
.FCTR  LB:  [  1  .  1  IFDOLRM/LB 


Add  HLL  Interface 
Add  FDO 


5.9    The  Interface  for  COBOL-11 

In  COBOL  programs,  only  data  names  may  be  passed  as  ar^juments.  except  iji 
the  cases  i,i  KIH'I'L  and  FLOPEN.  All  values  that  are  passed  must  have  been 
defined  in  the  data  division  ot  the  program.  No  string  literals  or  numeric 
constants  are  allowed. 
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The  COBOL  interface  assumes  two  specific  data  types  when  passing  data  to 
and  from  the  Form  Driver.  These  data  types  are: 

for  strings:  left  justified  sign  separate 

for  numbers:  computational 

See  Table  5-9  for  a  list  of  COBOL  arguments  that  shows  the  necessary  data 
types.  You  may  create  your  own  dava  structure  provided  that  you  use  the 
listed  data  types  in  your  Form  Driver  calls. 

COBOL  tasks  should  use  the  Form  Driver  with  RMS  support. 

To  avoid  loss  of  typeahead  on  RSX-llM  and  RSX-llM-PLUS,  FMS  appli- 
cations must  attach  the  terminal.  This  is  done  by  calling  the  subroutine 
''WTQIO",  the  queue  I/O  request  and  wait  call  (see  the  description  of  QIOW$ 
in  the  RSX-HM  Executive  Manual).  The  arguments  are  the  same  as  for  the 
FORTRAN  form  of  the  call:  LM'M  is  768  and  LUN  is  the  LUN  assigned  to 
the  terminal  for  the  Form  Driver  as  shown  in  the  following  example. 


INLIM  PIC    399        co(riF     walue     7G8  . 

LUN  PIC    9  comp     ual Me     1 . 


CALL  "WTOIO"  USING  INUM.LUN.LUN 


5.9.1    Using  the  Form  Utility  (FUT)  to  Create  the  Communication 
Structure  for  a  COBOL  Program 

The  Form  Utility  (FUT)  creates  the  communication  structure  for  a  form  used 
by  a  COBOL  program.  (See  Chapter  :]  on  the  Form  I'tility.)  In  response  to  the 
/CC  opticm.  FUT  creates  a  COBOL  library  file.  The  output  is  a  text  file  with 
the  default  file  type  .LIB. 

At  compile  time,  you  request  the  library  file  by  means  of  a  COPY  command  in 
the  data  division  of  your  program.  (See  the  PDP-ll  COBOL  Language  Refer- 
ence Manual  for  details  on  the  COPY  command.) 

(Iroup  items  created  by  FUT  have  the  same  names  as  the  lield  names  in  the 
form  that  you  are  using. 

The  library  tile  contains  the  necessary  communication  structure.  If  you  do  not 
wish  to  use  the  structure  provided,  you  nuiy  create  your  own. 

The  output  of  the  Form  Utility  is  in  terminal  format  with  respect  to  the 
COBOL  program.  If  you  want  to  u.se  conventional  format,  you  must  reformat 
the  file.  (See  (he  Ref(trmat  utility  in  the  I'DI'  11  COHOL  I'ser's  (iuide.  On 
COBOL  program  formats,  see  the  PUP  1 1  COBOL  Lan^ua^e  Reference  Man- 
ual.) 

Chapter :?  includes  an  example  ol  the  COBOL  structure  that  the  Form  Utility 
can  produce. 
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5.9.2    Arguments  for  the  Calls 

Table  5-9  lists  typical  PDF  11  COBOL  data  types  and  data  structures  tor 
each  of  the  arj^uments  in  the  Form  Driver  calls. 

Table  VH:     Typical  COBOL!  I  Data  Types  for  Form  Driver  Arguments 


ArKunient 
Abbreviation 


Purpose.  Data  Type,  and  Picture  Attributes 


CHAN 
FID 

KIDX 
Kl.KN 
KIAM 


Channel  nunil)iT:  l)iiiiiry  index. 

I'uture:  niic  worfl  cnrnpuliitinnal.  >ynrhrtini/('(l  left. 

Field  iiiune:  (i  ihanuter  >trint;. 

i'irtiire:  any  iliaraeler.  blank  padded    left  justified,  si^'ti  sepa- 
rate, syiuhrimi/ed  lelt . 

Field  and  named  data  index:  binary  index. 
I'irlure:  nr\"  word  cutniJUtatiiinal.  syiuhroni/.ed  lelt. 

Field  length:  bniary  index, 

I'ietiire:  imi'  wurd  loinputalitmal.  s\iuhriMii/ed  lelt. 

Form    librar\    file  specitiiatKin:    a  string   whose   len^'th   is   the 
len^'l 

Iters  that  em  lose  the  speiiliiat  ion 

I'uture;  any  charaiter,  blank  padded,  lelt  justilied.  sign  sepa- 
rate, svni'hronized  left. 


h  ol  the  tile  specitiealion  plus  two  thaiacters  lor  the  delim- 


FNA.MK 


F\AI. 


IMI".  KK 


I.INF 

SI/.K 
SiATrS 

.-^lAI-J 

IKini 


Form  name:  <i characier  string, 

i'uture:  am  eharacter.  blank  padded,  lelt  justitied.  sign  sepa- 
rate. s\nt  hroiu/ed  lelt , 


Named  data  value,  one  or  more 


field  values,  text  for  display  on 


the  bottom  sireen  line,  .A  string  wl 


lose 


length 


is: 


For  a  single  field  value,  the  length  o(  the  field. 


For  a  string  ot  lield  value 
to  be  proeesssed. 


..  the  sum  of  the  lengths  of  all  fields 


•or  a  naitu'c 


maximum  tiO    actual 


I  data  \alue.  the  length  ol  the  named  data  field 


length 


is  variable 


For  text  to  be  displayed  on  the  bottom  line,  the  length  of  the 
text  plus  ■_'  tharaiters  for  the  delimiters  that  eiulose  the  text. 


Impure  area;  (using  the  impuri' 


area  si/e  that  the  Form  Kditor 


and   Form   ItihiN    report,  the  si/e 


it  th 


e  subst  ripted  \ariabli 


-hoiild  be  m,  bvtes  larger  than  the  largest  impure  area  tor  the 
lorm-  that  the  apjiluation  uses). 

Starting  line  numl)er  for  a  displayed  form:  binary  index. 
I'uture;  one  word  computational,  svnchroni/ed  lelt. 


ihe 


si/e  ol  the  impure  area  in  b\tes. 


i  lelt. 


Call  eotiipletion  status:  i)mar\   index 

Picture;  one  word  sigiu-d  compuiational.  s\ni  hroi'ii/.e< 

FCS  or  KMS  s\stem  error  lode;  binarv  index 

Picture:  one  word  signed  (omputational.  s>iuhroiu/ed  lelt. 

Field  terminator  (ode;  binar\   iiulex, 

Puture:  one  word  (two  bvtesi  computational,  svm  h.om/ed  lelt 
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5.9.3    Syntax  for  the  Calls 


All  ot  the  Form  Driver  calls  use  the  CALL  statement,  'i'ahle  a  lo  summarizes 
the  principal  purposes  and  shows  the  full  CALL  statement  syntax  tor  e.ich 
call.  The  arguments  that  you  must  sui)pl\-  are  in  lowercase  letters,  and  oj)- 
tional  arguments  are  enclosed  in  square  brackets  (  [  and  !  I.  The  torms  of 
calls  that  have  no  arguments  are  listed  separately.  The  argument  abbrevia- 
tions and  purposes  are  fully  described  in  Table  5   10. 


Table  5-10:     Listing  of  COBOL-1 1  Form  Driver  Calls 


(all 
Abbreviation 


FCI^KSH 


WAV 


FdKT 


FCIKT.AF 


Summarv  and  Forms 


Ck'jirs  the  entire  screen  aiul  (ii>i)lays  the  Idrtn  with  delaiilt  lield 
values.  It  a  line  niiiiilier  is  specified,  uses  it  a>  the  starling'  hue 
iunnl)er  Inr  the  lurni. 

The  t(irni  is:  CALL   "FCLPSH"   USING  BV   DESCRIPTOR    [nam 

!,PV  REFERENCE  Unci 

Returns  the  tield  name  troni  tie  Furni  Driver  ar^Minient  hst  (and  it 
it  is  an  indexi'd  tield,  il^  index L 

'I'he  t(iriii  is;  CALL    "FGCF"   USING  BY  DE5CR  I  PTOR /V(/ 

i.BV   REFERENCE  fidx]. 

it  a  lield  name  is  spei'it'ied.  ^ets  and  returns  the  \alue  tor  the  tit'ld 
and  the  tield  termmatdr  u>ed.  It  im  tield  name  is  speeilied.  syn- 
ihr(ini/es  the  jjrd^'ram  with  the  nperatnr. 

The  torms  are:  CALL  "FGET"  USING  BY  DESCR  I  PTOR  /(«/. 

BY  REFERENCE  Irnu. 
BY  DESCRIPTOR  fid 
l.BY  REFERENCE  fid.x]. 
CALL  "FGET" . 

(iets  and  returns  the  value,  tield  name  land,  it  the  lield  is  indexed. 
its  indexl.  and  the  lield  terminator  u>ed  Inr  the  lield  that  the 
operator  thooses. 

The  form  is:  CALL  "FGETAF"  USING  BY  DESCRIPTOR  fial. 

BY  REFERENCE  tcr-n. 
BV  DESCRIPTOR  fid 
l.BY  REFERENCE  fid.xi. 


I 
I 


FCKIAI. 


FID.MA 


II  the  call  inchuios  an  a.'mimeiit,  irets  and  returns  a  concatenated 
strint:  ol  ail  lield  values  land  o|)tir.nall>  the  last  lield  terminator 
usedl.  Il  no  artiuments  are  spetilied.  ;;cts  all  valuer  hut  oniN  stores 
them  in  the  impure  art  a. 

The  lorms  are:  CALL   "FGETAL"   US  I  NG  B  Y  DESCR  I  PTOR  /i  (W 

1  .BY  REFERENCE  Irrm] 
CALL   "FGETAL" . 

(lets  and  returns  the  named  data  val'.ie  that  has  the  index  *peci- 
lied 

The  lorm  is:  CALL   "F  I  DATA"  US  I  NG /'k/.v. 

B'l    DESCRIPTOR  friil. 


Iciinliruicd  on  lU'xt  pajie 


I 
I 
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Tabie  5-10  (Cont.): 

Listing  of  COBOL!  1  Form  Driver  Calls 

(all 
Abbreviation 

Summary  and  Forms                                                              ^^B 

FIMl- 

Supplies  to  the  Forni  Driver  the  name  ot  the  impure  area  lu  use 
and  its  size.  This  call  returns  it  own  status  code  if  the  thu-d  argu- 
ment is  speeii'ied. 

1 

The  form  is:  CALL  "  F  I  N  I  T  "  US  I  NG  BY  DESCR  I  PTOP  impure. 

BY  REFERENCE  si:c  [.status]. 

1 

FINI.X 

(Jets  and  returns  a  concatenated  string;  of  the  field  values  for  the 
current   line  of  the  scrolled  area  that  contains  the  specified  field 
name  and  the  last  terminator  used. 

'I'he  f<  )rm  is:  C  A  L  L  "  F  !  N  L  N  "  U  S  I  N  G  B  Y  D  E  S  C  R  I  P  T  u  R  fid,  j\al 

BY  REFERENCE  term. 

FLCHAN 

Supplies  to  the   form  Driver  the  I.'O  channel   (LrX)  to  use  tor 
reading  a  lorm  library  file. 

1 

The  form  is:  CALL    "FLCHAN"   USING  chan.                                                               ^^k 

KI.CLOS 

("loses  the  current  torm  library  file. 

1 

The  form  is:  C  ALL   "  FLCLOb  "  . 

1 

K  I.F.N 

Returns  the  lenjith  of  the  specified  fielcF 

The  form  is:  CALL   "FLEN"   USING  /7«7?,  BY  DESCR  I  PTijR /Yf/ 

I.BY  REFERENCE  fidx]. 

FI.()PF:\ 

Opens  the  specified  form  library  tile. 

1 

The  form  is:  CALL   "FLO PEN"   USING  BY  DESCRIPTOrv  /■/„,„.                          ^B 

1 

FXDATA 

(lets  and  returns  the  named  data  value  that  has  the  nan.cd  data 
label  specified. 

The   lorm   is:   CALL    "FNDATA"    USING    BY    DESCRIPTOR  fid, 
fvdi. 

1 

Forii.N 

Displays  the  specified  string  of  field  values  in  the  current  line  of 
the  scrolled  area  that  contains  the  spt'citied  field. 

The  form    is:    CALL    "FOUTlN"    USING    BY    DESCRIPTOR  fid.                         ^^ 

1 

FI'FT 

If  the  call  includes  an  argument.  i)rocesses  the  sjjecified  field  ter- 
minator and  identifies  the  appro|)riate  field  as  the  current   field. 
(To  find  the  current  field  name,  ust^lie  FdCKcall.)  If  the  specified 
terminator  is  a  scrolled  area  terminator,  the  name  of  a  field  in  the 
intended  sirolled  area  must  be  spetified.  and  if  a  string  of  values  is 
specified,  they  will  be  displayed  on  the  top  or  bottom  lint'  of  the 
scrolled  area  after  the  terminator  is  processed.  If  no  argument  is 
included,  the  call  proces.ses  the  last  terminator  th.at  was  used. 

The  forms  are:  CALL   "FPFT"  USING  term 

[.BY  DESCRIPTOR    fid  Ifral]]. 
CALL   "FPFT" , 

1 

Fl'l   r 

Displays  the  specified  value  in  the  s|)ecified  field. 

The  form  is:  CALL   "FPUT"   USING  BY  DESCR  I  PTOR /if//,  fid 

I.BY  REFERL^'CE  fid.x].                                                ^^ 

(continued  on  next  pajje)                   ^^^ 
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Table  5-10  (Cont.):     Listing  of  COBOL- 1 1  Form  Driver  Calls 


Call 
Abbreviation 


FFITAL 


FPITL 


FRKTAL 


Summary  and  Forms 


Displays  valuos  in  all  fields  ot  ihe  lorni.  ll  a  c 

values  is  suijplied.  each  value  must  be  the  same  length  as  the  tield 


oiu'aleiiated  slrnit;  i>l 


HI   VV 


hieh  it  is  to  he  displaved  and  th 


e  values  must  he  in  the  same 
)ider  that  the  FCKTAL  call  would  prodiiie  lor  the  lorm.  Values 


trom 


the  St 


rinji  supplied  are  displayed  in  the  first  t'iehls  ot  the  I 


and  defaults  are  displayed  in  any  lields  that  remain.  It 
values  is  su|)|)lied,  default  values  are  displascd  \n  all  I 


orm. 
no  strin"  ol 


lelcls, 


The  forms  are:  CALL  "FPUTAL' 
CALL    "FPLITAL' 


USIfJG  BY  DESCrv  IP  TOP /(,;/. 


If 


an  argument   is  speeified.  displays  the  specified 


irint;  o 


n  tht 


bottom  line  of  the  screen.  If  no  argument  is  .specified,  clears  the 
bottom  line. 

The  forms  are:  CALL   "FPUTL"   USIhJG  BY  DESCR  I  PTDR /Vo/. 


CALL    "FPUTL 


Returns  the  current  values  for  all  fields  in  the  for 
order  that  the  FOKTAL  call  would  produce. 


m  in 


th 


e  same 


FRKTN 


FSHOW 


The  form  is:  CALL   "FRETAL' 


U S  I  N  G  B  1'   D E  3  C  R  I  P  T  0  R  fvnl. 


Returns  the  current  value  of  the  specified  tield. 

The  form  is:  CALL  "FRETN"  USING  BY  DE5CR  I  PTOR /ra/.  fid 

i.BY  REFERENCE  fid.x]. 

Clears  the  part  of  the  screen  that  the  specified  torm  recjuires  and 
displays  the  form  with  default  tield  \alues.  It  a  line  number  is 
specified,  uses  it  as  the  starting  line  number  tor  the  t 


orm. 


FSFOFF 


Th 


e  torm  is:  CALL   "FSHOW"   USING  B' 


DESCRI  PTUR  [nam 


,BY  REFERENCE  lirw 


Turns  oft  the  Supervisor  ()nl>  mode  and  allows  the  oi)erator  t( 
enter  and  change  data  in  fields  to  which  the  Supervisor  Only  at- 
tribute was  assigned  with  the  Form  Kditor, 


FSPON 


FSTAT 


The  f( 


irm  is:  CALL   "FSPOFF 


or  trom 


Turns  on  the  Supervisor  Only  mode  and  prevents  the  operat 
entering  or  changing  data  in  fields  to  which  the  Supervisor  Onl> 
was  assigned  with  the  Form  Kditor. 


The  form  is:  CALL   "FSPON"  . 

Returns  the  status  code  for  the  last  call  that  wa 
value  ol  the  first  argument,  The  value  ot  the  second  argument 
eaningliil  as  an  FC,-.  or  RMS  system  error    ode  (de|)ending  on  the 


s  |)rocessed  as  the 


IS 


m 


th 


e  value  ot  i  he  lirst 


version  of  the  Form  Driver  in  usel  only  it 

argument  is    ■}  or     18.  indicating  an  error  while  Irving  to  ojiin  or 

read  a  form  librarv  file. 


I 


The  t. 


irm  is:  CALL   "FSTAT"   USING  sl(itus\.st(ifj]. 
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5.9.4    Building  a  COBOL  Task 

The  following  command  files  illustrate  how  to  build  a  non-overlaid  COBOL 
task  COBDEM.  For  more  information  refer  to  the  RSX-IJM  Task  Builder 
Manual  or  the  IAS  Task  Builder  Reference  Manual. 

For  RSX-llM  and  RSX-llM-PLUS: 


;     COBDEM.CMD 


I 
I 


C  0  (I)  (ii  a  ri  d  file  to  bnj  i  1  .j  COBOL  ij  e  in  o 


[ 170  taO] COBDEM  ,1 170  » 30 ] COBDEM / -  5 P = [ 170  .20] COBDEM 

? 

5        COBOL  interface  and  F  o  r  (n  Driver  1  i  b  r  a  r  ••  , 

•i 

[ 150  .20]HLLC0B  »[ 120  tZODFDOLRM/LB 

7 

LB:  [ 1  . 1  ICOBLIB/LB  .RMSLIB/LB 

UNITS=9 

i         L  U  N  1  I.I  1  1  1  be  the  t  e  r  m  i  ri  a  1  . 

ASG  =  TI : 1 

i         L U N  3  will  be  the  output  file  u ri  1 1  . 

ASG  =  SY:3 

!         R  e  a  s  5  1  d  )"i  the  1  o  3  i  o  a  1  unit  in  the  Form  Driver 

GBLDEF  =  T$LUN:1 

// 

1 


For  IAS: 


COBDEM.CMD 


C  0  iTi  (II  a  riij     file     to     t'  u  i  1  d     I'l  e  ui    COBOL     d  e  m  o 

(using  "CALL  BV  DESCRIPTOR'  feature  of  COBOL  04.1) 


r.  11  .llGlCOBDEM.Clll  .11G]C0BDEM/-SP=[11  .IIGICOBDEM 

COBOL  interface  and  Form  Driver  Library 
[11  .  1  IBIHLLCOB  .LB:  [  1  .  1  IFDOLRM/LB 

LB:[1  .nCOBLIB/LB.Cl  .1]  RMS  LIB/LB 

/ 

UNITS^S 

!         L  U  N  1  1.1 1  1  1  be  the  t  e  r  iti  i  ii  a  1  . 

ASG  -     TI : 1 

;        L U N  3  I.I  1  1  1  be  the  output  file  li nit. 

ASG  ^  SY:3 

;        Reassidri  the  logical  li  vi  it  i  ii  the  Form  D  r  i  u  e  r  . 

GBLDEF  =  T*LUN:1 

// 
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The  following  command  file  illustrates  building  a  non-overlaid  COBOL  task 
using  the  DCL  (PDS)LINK  command  on  IAS: 


I  COBDEM.CMD 
I 

'  Com  III  a  i-id  file  to  build  COBOL  d  e  di  o 
I 

L  INK  'MAP :COBDEM/ OPT  IONS 

COBDEM  tC  11  ,1  IGIHLLCOB  .LB:  [  1  ,1  ]  FD^'LTyM ,  L  I  B  -- 
LB:  [  1  »1  ICOBLIB/LIB  .LB:  [  1  .  1  ]  rvMSL  I  B  ,  L  I  B 
I  HLLCOB  -  COBOL  interface 
I  F  R  M  L  I  B  -  Form  Driver  1  i  b  r  a  r  ■/ 
UNITS=3 

I  L  L)  N  1  will  be  the  t  e  r  di  i  n  a  1  . 
ASG  =  TI  :  1 
I 

L  U  N  3  ui  1  1  1  ti  e  the  o  li  t  p  u  t  file  unit. 

ASG^SY :3 

I  Reassign  the  logical  unit  in  the  Form  D  r  i  ■■  ■  e  r 
GBLDEF-T$LUN: 1 

/  / 


Note  that  when  a  COBOL  application  is  task  built  as  indicated,  the  option 
GBLDEF  -  T.$LLN:1  produces  the  following  diagnostic  message: 


TKB  --  *DIAG*-MODULE  FDUDAT  MULTIPL' 
DEFINES  SYMBOL  T$LUN 


This  is  only  a  warning  message  and  will  not  impact  the  application. 
Here  is  a  complete  sample  sessicm  to  compile  and  build  a  COBOL  program: 


CBL     COBDEM. CGBDEM  =  COBDEM/ ERR  :1 
TKB     iiCOBDEM.CMD 
RUN     COBDEM 


I 


It  is  highly  recommended  that  you  use  the  compiler's  /ERR:1  option  because 
Form  Driver  calls  allow  a  variable  number  of  arguments.  If  you  do  not  use  the 
/ERR:1  switch  option,  COBOL  will  produce  warnings  when  you  use  optional 
argument  lists.  However,  the  /ERR:1  option  also  suppresses  other  warning 
diagnostics. 


If  you  elect  to  build  an  overlaid  COBOL  application,  problems  may  arise 
during  task  building.  This  can  occur  if  the  COBOL  MER(;E  I'tility  is  used 
and  the  resulting  ODL  file  edited.  This  is  the  result  of  the  task  builder  not 
accepting  files  with  lines  longer  than  80.  characters.  ("OBOL  MERC.E  creates 
lines  which  are  blank  filled  to  exactly  80.  characters.  If  you  use  an  editor  to 
modify  the  ODL  file,  characters  will  be  inserted  and  the  lines  will  be  longer 
than  the  task  builder's  maximum.  This  problem  can  be  solved  by  deleting  all 
trailing  blanks  from  any  line  which  is  modified  bv  an  editor. 


Form  Driver  I'rogramminfi  Heqiiirements  and  Concepts    5-29 

May  1981 


The  foll()winf(  is  an  example  of  the  Task  Builder  command  sequence  and  the 
overlay  descriptor  file  for  an  overlaid  COBOL  prof,Tam  usin^  FMS.  The  ODL 
file  was  created  bv  COBOL  MERGP]  and  modified  to  include  FMS  files. 


! 


TKBODL  .CMD 

To  task  bi.iild  CGUIDE  with  CGTEMP.QDL 


CGU  I  DE  .  CGU  I  DE  /  -  SP  /  CR  =:  CGTEM  P  /  MP 

UNITS=9 

!         L  U  N  1  will  bi  e  the  terminal. 

ASG  =  TI : 1 

;         L  U  N  2  I  3  I.I  1  1  1  be     the  R  D  W  R  T  output  files  i.i  n  i  t  s  . 

;         LUN  a  15  for  form  lib.  argument  to  routine  "FLCHN". 

ASG  =  SY:2:3:<a 

i         Reassign  the  logical  unit  in  the  Form  D  r i n  e  r  . 

GBLDEF  =  T$LUN: 1 


FRMl  : 
FORM  : 

;merge 

;CQBOL 

;coBaB 
;cobke 

iCOBMA 


A  1  0  0  1  $ 
AlDi.'R$ 
;COBOL 
;COBOB 
;COBKE 
iRMSRE 


D 

S 
J  = 
R  = 
IN 


S 
J  = 
R  = 
0  = 


:zooi* 


zzooz$ 

ZZQi.iRt 
CBOBJ* 
CBOVRt 
CBOTS* 

CNi.'RT$ 
LDCUT$ 
USRIO$ 
QTSOU* 
@LB: [ 1 

RMSTRf 

RMS*: 

OBJRT$ 


.FCTR    FDi.iLRM.OLB/ LB 
.FCTR    HLLCOB.OBJ-FRMl 
ODL  FILE  CREATED  ON  IB-JAN- 
TANDARD  ODL  FILE  GENERATED 
CGUIDE. OBJ 
Al 

.  NAME  AltOOl  ,GBL 
.PSECT  *A1001  .GBL  .1  .RW  .CON 
.FCTR  ♦A1$001-$A1001 
.FCTR  A 1001$ 

TANDARD  ODL  FILE  GENERATED 
RDWRT .OBJ 

CI00Z7 

.NAME  ZZ$001  .GBL 

.PSECT  $ZZ001  .GBL  .  I  .RW  .CON 

.FCTR  #ZZ$001-$ZZ001 

.NAME  ZZ$OOZ  .GBL 

.PSECT  tZZOOZ  -GBL  .1  .RW  .CON 


80 
ON 


AT 
IB- 


15:^9:23 
JAN -80 


15:43:39 


ON:  ie-JAN-80 


15:45: 10 


^ 


FCTR 
FCTR 
FCTR 
FCTR 
FCTR 
NAME 
FCTR 
FCTR 
FCTR 
FCTR 


*  Z  Z  *  0  (J  2  -  *  Z  Z  ij  0  2 

ZZ001$  .ZZ002* 
CGUIDE. OBJ-RDWRT .OBJ 
AlOOR*  .ZZOORf 
LB: [  1  .1 ICOBOOR  LB 
OTS*00 

.1 ICOBOOR 

.  1 ICOBOUR 


■LB 
LB 


:CONOER 
:LDCOT 
1  ]C0B00R/LB:USR5I0 
-  ( CNORTf- ( ♦LDCOT$ ) 


LB:  [  1 
LB:  [  1 
LB:  [  1 

OTS$OU- ( CNORTf- ( ♦LDCOT$ )  .♦USRIO$  i 
1  IRMSl IS. ODL 
.NAME  RMS*TR 

RM5$TR-RMSALL 

RMSROT 
CB0BJ*-CB0TS*-F0RM-RM5$ 
OBJRT$-  1  CBO'.»R$  )  .RM5TR*  .OTSOOt 


FCTR 
FCTR 
FCTR 
ROOT 
END 
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5.10    The  Interface  for  FORTRAN  IV  and  FORTRAN  IV-PLUS 

The  calling  sequences  for  FORTRAN  IV  and  FORTRAN  IV-FLUS  are  identi- 
cal. 

Numeric  arguments  must  be  one-word  integers.  If  you  use  real  numbers  or 
bytes  instead,  the  calls  do  not  work  {)roperly. 

Strings  returned  from  the  P^)rm  Driver  are  ASCTZ.  and  strings  input  to  the 
Form  Driver  must  be  ASCTZ.  "ASCIZ  strings"  contain  a  null  byte  as  their  last 
character.  Thcefore.  programs  must  allocate  an  extra  byte  for  data  returned 
irom  the  Form  Driver. 

For  literals  enclosed  in  quotation  marks  that  are  passed  as  arguments.  FOR- 
TRAN generates  ASCIZ  strings.  The  best  way  to  implement  string  variables 
is  by  means  ot  byte  arrays.  The  variables  can  be  passed  as  arguments  and 
tnanipulated  one  character  at  a  time.  The  data  in  the  arrav  must  end  with  a 
null. 

All  subroutines  may  be  called  either  as  subprograms  or  as  functions.  If  they 
are  called  as  functions,  the  name  of  the  routine  must  l)e  declared  in  an  integer 
statement  or  an  implicit  integer  statement  (for  example.  IMFLKTT  INTE- 
(iKR  (Fl).  If  called  as  (unctions,  the  subroutines  return  the  status  of  the  call 
from  the  Form  Driver  on  output. 

FORTRAN  IV  PLIS  programs  can  use  the  Form  Driver  with  F(\S  or  RMS 
support. 

FORTRAN  IV  programs  should  use  the  Form  Driver  with  FCS  support.  To 
avoid  loss  of  typeahead  on  RSX  1!\I  and  RSXllM  FIT'S.  FMS  applica- 
tions must  attach  the  terminal.  The  FORTRAN  programmer  attaches  the 
termin^il  with  the  high-level  language  interlace  "WTQIO"  call,  (see  the  de- 
scription of  QIOW.S  in  the  USX  1 IM  Exvcutiic  Manual)  which  is  the  queue 
I/O  request  and  wait  call.  The  INT'M  is  768.  Ll'N  is  the  Ll'N  assigned  as 
terminal  for  the  Form  Driver. 


CALL     WTQiO     (7G8.5.5) 


5.10.1    Arguments  for  the  Calls 

Table  :>   11  lists  typical  FORTRAN  IV  and  FORTRAN  IV  FIT'S  data  types 
and  data  structures  for  each  of  the  arguments  in  the  Form  Driver  calls. 
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Table  5-11:    Typical   FORTRAN   IV   and   FORTRAN   IV-PLUS   Data 
Types  for  Form  Driver  Arguments 


Argil  niont 
Abbreviation 


CHAN 

KID 

FIDX 

KKKA 

Kl.NM 

FNAMK 
F\AL 

IMITKK. 

LINK 
SIZF. 

siA'irs 

SrAT2 
IKKM 


Purpose.  Data   lype.  and  Data  Strueture 


Channel  niiiiilxT:  inlc^'iT  \ari,il)U'  or  (■(m>tant. 

Fifld  namr:  7-l)yt('  string  \ariahio. 

Fifld  and  nainod  data  mdox:  inti'^ii-r  \arial)lt'. 

Fii'ld  li'n^'th:  init'^'tT  variable. 

Fiirm  Hhrarx  tile  specitication:  >trin^  nr  i'iin>tani  itlie  >i/e  depends 
nil  appliialinn  re(|iiirenients  and  ennxcnlMinsi, 

Fiirm  natne:  7i)\te  string  \ariat)le  nr  constant. 

Named  data  value,  niu'  or  more  tield  values.  ti'Xt  lor  displav  on  the 
hdttoni  sereen  line:  string;  \ariahle  (the  si/e  depend-  on  t  hi'  api)ii- 
cation). 

Impure  area:  livte  array  (using  the  impure  area  size  that  the  Form 
Kditor  anri  Form  I'tility  report,  the  si/e  ol  the  array  should  he  (il. 
bytes  larjjer  tlian  the  largest  impure  area  tor  the  tonus  that  t  he 
a|)plitation  uses). 

Starting  line  numhi'r  lor  a  (lis|)layed  form:  integer  \ariahle  or  inn- 
stanl. 

The  si/e  ot  the  imiture  area  array  in  bytes. 

Call  completion  status:  integer  \ariable. 

FCS  or  RMS  system  error  code:  integer  variable. 

Field  terminator  code:  integer  variable. 


5.10.2    Syntax  for  the  Calls 

All  ol'  the  Fonii  Driver  calls  use  the  (^Al.L  statement.  The  f'utution  subpro- 
^'ram  form  can  also  he  used.  Tnljle  .")  12  summarizes  the  j)rinci|)al  purposes 
and  ishovvs  the  lull  CALL  statement  syntax  tor  each  call.  The  arguments  that 
you  must  supply  are  in  lowercase  letters,  and  optional  arjiuments  are  enclosed 
in  square  brackets  (  |  and  1  ).  The  lorms  of  calls  that  have  no  arguments  are 
listed  separately,  'i'he  argument  abbreviations  and  purposes  are  lully  de- 
scribed in  Table  ")  11. 


Table  5-12:    Listing  of  FORTRAN  IV  and  FORTRAN  IV-PLUS  Form 
Driver  ('alls 


Cull 
Abbreviation 


FCI.HSH 


Summarv  and  Form!: 


Clears  the  entire  sireeii  and  displays  the  form  w    '  the  delaiill  lield 
values.   II  a  lin«'  number  is  specilied,  uses  ■  the  starting  line 

number  tor  the  lorm. 


The  iorni  is;  CALL  FCLT'/SHlfndml.linr]) 


Icotiliniied  on  next  page) 
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Table  5-12  (Cont.):    Listing  of  FORTRAN  IV  and  FORTRAN  IV-PLUS 

Form  Driver  Calls 


Call 
Abbreviation 


FGCF 


FGET 


F(^.RTAF 


F(;KTAL 


FIDATA 


FINIT 


FINLN 


FLCHAN 


FL(M.()S 


FLK.\ 


FI.OPF.N 


FXDATA 


Summary  and  Forms 


Returns  the  field  name  from  the  Form  Driver  ar^^ument  list  land  if 
it  is  an  indexed  tield.  its  index). 

The  form  is:  CALL  FGCFf/Vrf!,/(f/.vli 

If  a  field  name  is  pecified.  jjets  and  returns  the  value  for  the  field 
and  the  field  terminator  used.  If  no  field  name  is  specitied.  syn- 
chronizes the  prof^ram  with  the  operator. 

The  forms  are:  CALL  FQEKfrcil.tcrm.fidlfid.x]) 
L ^LL  FGET 

Gets  and  returns  the  value,  field  name  land,  if  the  field  is  indexed, 
its  index),  and  the  field  terminator  used  for  the  field  that  the 
operator  chooses. 

The  form  is:  CALL  FGET f)Flfr(il. term. fidi.fidx]) 

If  the  call  includes  an  argument,  gets  anci  returns  a  concatenated 
string  of  all  field  values  (and  optionally  the  last  field  terminator 
used).  It  no  arguments  are  specified,  gets  all  values  but  only  stores 
them  in  the  impure  area. 

The  forms  are:  CALL  FGETALf/ra/I./cmilJ 
CALL  FGETAL 

Gets  and  returns  the  named  data  value  that  has  the  index  speci- 
fied. 

The  form  is:  CALL  F  IDf^J  Mfidx.fral) 

Supplies  to  the  Form  Driver  the  name  of  the  impure  area  to  use 
and  its  size. 

The  form  is:  CALL  F  lHlJ(impun\si:r[,.'itatiis\) 

(iets  and  returns  a  concatenated  string  of  the  field  values  for  the 
current  line  of  the  scrolled  area  that  contains  the  specified  field 
name  and  the  last  terminator  used. 

The  form  is:  CALL  F  INLNifid.fral.tcrm  i 

Sup|)lies  to  the  Form  Driver  the  lO  channel  ll  '  \ )  to  use  for 
reading  a  form  lilirary  file. 

The  form  is:  CALL  FLCHANrc/jrj/n 

Closes  the  current  form  library  file. 

The  form  is:  CALL  flcLOS 

Returns  the  length  of  the  specified  field. 

The  form  is:  CALL  FLEN([lrn,fid\.fid.\]l 

Ojjens  the  specitied  form  library  file. 

The  form  is:  CALL  FLOPEWflnm) 

Gets  and  returns  the  named  data  value  that  has  the  named  data 
label  specified. 

The  form  is:  CALL  FHDf^TMfidJial)  ,        ..         , 

(contmued  on  next  pajje) 
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Table  5-12  (Cont.):    Listing  of  FORTRAN  IV  and  FORTRAN  IV-PLUS 

Form  Driver  Calls 


Call 
Abbreviation 


FOITLN 


FPFT 


FPIT 


FPITAL 


Fjn  TL 


FRKTAL 


FRKTN 


FSHOW 


FSl'OFF 


Summary  and  Forms 


Displays  the  spei'ified  string;  nt  Held  values  in  the  current  line  ol' 
the  scrolled  area  that  contains  the  specified  field. 

The  form  is:  CALL  fOUTLUI fid. fval) 

11  the  call  includes  an  artrument,  processes  the  specified  field  ter- 
minator and  identifies  the  appropriate  field  as  the  current  field. 
(To  tind  the  current  tield  name,  use  the  FdCF  call.)  if  the  specified 
terminator  is  a  scrolled  area  teniiinator.  the  name  ot  a  field  in  the 
intended  scrolled  area  must  be  si)ecified,  and  it  a  string  ot  values  is 
specified,  they  will  he  d  ijlayed  on  the  top  or  bottom  line  ot  the 
scrolled  area  alter  the  terminator  is  processed.  If  no  argument  is 
included,  the  call  processes  the  last  terminator  that  was  used. 

The  forms  are:  CALL  FPFTf^77?!i,/Vf/l,/V«/lU 
CALL  FPFT 

I)isi)lays  the  specified  value  in  the  s])ecifie(i  tield. 

The  form  is:  CALL  F PUK fral.lid[.fidx\) 

Displays  values  in  all  tields  of  the  form.  It  a  concatenated  string  of 
values  is  sup|)lied.  each  value  must  be  the  same  length  as  the  field 
in  which  it  is  to  be  displayed  and  the  values  must  be  in  the  same 
order  that  the  FCiKTAL  call  would  produce  for  the  form.  Values 
fnmi  the  string  supplied  are  displayed  in  the  first  fields  of  the  ibrm. 
and  defaults  are  disjjlayed  in  any  field  that  remain,  it  iio  string  of 
values  is  supplied,  detault  values  are  displayed  in  all  tields. 

The  forms  are:  CALL  FPUTALf/Va/j 
CALL  FPUTAL 

It  an  argument  is  specified,  displays  the  specitied  string  on  the 
bottom  line  of  the  screen.  It  no  argument  is  specified,  clears  the 
bottom  line. 

The  torm>  are:  CALL  FPUJUfcah 
CALL  FPUTL 

Returns  the  lurrent  values  for  all  fields  in  the  form  in  the  same 
order  that  the  FdKTAL  lall  would  produce. 

The  form  is:  CALL  FRET ALr/ra/^ 

Returns  the  iiirrent  value  of  the  specified  field. 

The  form  is:  CALL  fri£TU(fiaifid\.fid.\]l 

Clears  the  part  tit  the  screen  that  the  specitied  form  re(|iiires  and 
displays  the  form  with  detault  field  values.  It  a  line  numl)er  is 
specified,  uses  it  as  th.e  starting  line  number  tor  the  form. 

The  form  is:  CALL  fSHOUIfiuimllinr]) 

Turns  off  the  Sujjervisor  Only  mode  and  allows  the  operator  to 
enter  and  change  data  in  fields  to  which  the  Supervisor  Only  at- 
tribute was  assigned  with  the  Form  Kdilor. 


The  form  is:  CALL  FSPOFF 


(continued  on  next  \m\(e) 
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Table  5-12  (Cont.):    Listing  of  FORTRAN  IV  and  FORTRAN  IV-PLUS 

Form  Driver  Calls 


Call 
Abbreviation 


Summary  and  Forms 


FSPON 


FSTAT 


Turns  on  the  Supervisor  Only  mode  and  prevents  the  operator  trom 
enterinf{  or  changing;  data  in  fields  to  which  the  Sujjervisor  Only 
was  assigned  with  the  Form  Kditor. 

The  form  is:  CALL  FSPON 

Returns  the  status  code  tor  the  last  call  that  was  processed  as  the 
value  of  the  tirst  argument.  The  value  of  the  second  argument  is 
meaningful  as  an  FCS  or  RMS  system  error  code  (depending  on  the 
version  of  the  Form  Driver  in  use)  only  if  the  value  of  the  first 
argument  is  4  or  18.  indicating  an  error  while  trying  to  open  or 
read  a  torni  library  tile. 

The  form  is:  CALL  fSJ f\J(statusl..st(it2]) 


5.10.3    Building  a  FORTRAN  Task 

The  following  command  files  illustrate  how  to  build  FORTRAN  tasks. 

For  RSX-llM  and  RSX-llM-PLUS:  | 


FDRDEM .CMD 

Bli  1  1  d  the  FORTRAN  demo 


FORDEM  .FORDEM/CR/ -SP  =  FORDEM 

FORTRAN  interface  and  Form  Drmer  library 
H  L  L  F  0  R  .  F  D  U  L  I  B  /  L  B 

Use  FDROTS  for  F4  or  F<aP0T5  for  F4+. 

LB : C 1  .1 ]FQROTS 'LB 

/  / 

F4PFCS.CMD 

Build  the  FORTRAN  demo  for  FORTRAN  1*,!+  u  s  i  n  3  FCS 

! 

iF4PFCS/FP.F^PFCS/CR/-SP=FaPDEM 
i 

1        FORTRAN  interface  and  Form  Driver  library 

HLLFOR  .FDi.'L  IB/LB 

J        Use  F4PFCS  for  F^+  with  FCS 

LB:  [ 1  .  1 ]FaPFCS/LB 

// 

? 

I 

i  F/JPRMS-CMD 


\ 


Build  the  FORTRAN  demo  for  FORTRAN  1'.'+  usms  RMS 
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F-aPRMS/FP.F4PRMS/CR/-SP  =  FaPDEM 

FORTRAN  interface  and  Form  Dri'ier  library 
HLLFOR  ,FD>.'LRM/LB 

Use  FaPRMS  for  Fa+  u s  i  n d  RMS 
LB :  [  1  »  1  ]F^PRMS/LB 

Also  include  the  RMS  library 


LB:  [  1  .1  IRMSLIB/LB 

// 

5 


For  IAS: 


FORDEM.CMD 

Build  the  FORTRAN  Demo 
[  11  ,11G]F0RDEM/FP  .[111  »  1  1  B ] FORDEM / CR / - S P = [ 11  »11G]F0RDEM 

FORTRAN  interface  and  Form  Driver  Library 
[11  ,1  IGIHLLFOR  .LB:  [1  .1  IFDULIB/LB 

Use  FOROTS  for  'Fa    or  F4P0TS  for  F^+. 

LB: [ 1  .1 IFOROTS/LB 
;LB:  [  1  .1  ]FaPOTS/LB 
// 

F<aPDEM.CMD 

Build  the  FORTRAN  demo  for  FORTRAN  iy+. 
[11  .nP^PDEM  .tl  11  .llG]FaPDEM/CR/-SP=[  11  .1  IGIF^PDEM 

FORTRAN  interface  and  Form  Oriner  library 
[11  ,1  IGDHLLFOR  .LB:  [ 1  .1  DFDUL IB/LB 

Use  FOROTS  for  R4  or  F^POTS  for  F<a+. 

LB  :  [  1  .1  IFOROTB/LB 
LB:  [  1  .1  ]F<yPOTS/LB 
// 

The  followinfi  command  files  illustrate  task  builds  of  FORTRAN  tasks  using 
the  DCL  (PDS)  LINK  command  on  IAS: 


FaPDEM.CMD 

Check  the  Form  Driner 
For  FORTRAN  IV-PLUS. 

LINK/MAP: FaPDEM/CRO 
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F-aPDEM.[ll  .11B]HLLF0R.LB:C1  »1]FDULIB/LI8,I,.B:[1  »l]F-aPOTS/LIB 

I 

!  Form  D r m e r  Library  FDULIB  includes  FORTRAN 

!  interface.  Use  F^POTS  for  F^+. 

I 

I  FORDEM.CMD 
! 

!  Check  the?  Form  D  r  i  m  e  r 

!  for  FORTRA'^.'  I O  , 

I 

LINK/MAP:FORDEM/CRO 

FORDEM  .[  1  1  .llBDhLLFOR  »LL';  [  1  .1  ]  FDULIB /LIB  »LB:C1  .1]F0RQTS/LIB 

!  Form  npiuer  I  i  L.  r  a  r  /  FDULIB  includes  FORTRAN 

I  interface.  Ube  FQROTS  for  f-a. 


5.11    The  Interface  for  MACRO-11 

In  MACRO  -11  programs,  you  can  call  the  Form  Driver  with  the  instruction: 

JSR   PC  .$FD'.' 

.$FDV  is  global 

RO  must  point  to  a  list  that  includes  both  necessary  and  function  depend- 
ent arguments.  Table  5-13  summarizes  the  argument  Hst. 

Table  5-13:    Offsets  and  Meanings  of  Necessary  and  Function  Dependent 
Arguments 


Offset 


iVIeaning 


F$P'NC         One-word  function  code. 

f'$RE]Q         One-word  required  arguments  li.st  pointer. 

F$NAM       One-word  pointer  to  ASCIZ  form  library  file  specification  or  pointer  to  6-byte 
ASCII  form  name,  field  name,  or  data  name. 

F$NUM       One-word  starting  line  number  to  display  form  or  index  value  for  field  or  named 
data. 

FSTRiVI        One-word  field  terminator  code. 

F$V'AL         One-word  data  pointer. 

F$LEN         One-word  data  length  (in  bytes). 


(F.$ASIZ  is  the  size  in  bytes  of  the  argument  list.) 

NOTE:  The  offsets  to  the  arguments  in  the  argument  list  are  defined  as  global 
symbols.  The  values  for  the  offsets  may  change  between  releases  of  the  soft- 
ware. For  this  reas(m.  you  should  always  refer  to  these  offsets  by  name  in  your 
applications. 

You  must  specify  the  $FI)VI)F  macro  in  a  .MCALI.  statement  and  invoke  it 
in  a  MACRO  task  to  define  F$ASIZ  so  that  you  can  use  the  symbol  to  allocate 
space  for  the  argument  list  at  assembly  time.  F.$RSIZ.  below,  also  is  defined 
by  the  .$FDVDF  macro.  The  $FDV1)F  macro  is  provided  in  the  library. 

You  must  specify  a  function  code  (F$FNC)  and  a  i)ointer  to  the  required 
arguments  list  (F.$RKQ)  for  each  i:iA\  to  the  Form  Driver.  But  you  do  not  need 
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to  specify  all  of  the  remaining  arguments  for  each  call.  Which  arguments  you 
must  supply  to  the  Form  Driver  depends  on  which  call  you  are  issuing  (in 
other  words,  which  function  code  you  specify). 

On  return  from  the  Ft)rm  Driver,  the  carry  bit  is  clear  if  the  Form  Driver 
completed  the  call  successfully  and  the  status  code  is  positive  (>0).  All  regis- 
ters are  preserved  across  a  call  to  the  P\)rm  Driver.  If  an  error  occurred,  the 
carry  bit  is  set  and  the  Form  Driver  returns  an  error  code  in  the  status  block. 
If  you  specified  an  invalid  (undefined)  function  code,  the  error  code  FE$FCD 
is  returned.  Each  call  description  in  Chapter  6  includes  the  errors  specific  to 
that  call. 

The  two  necessary  arguments  in  the  argument  list  are  F$FNC  and  F$REQ. 
The  other  arguments  listed  in  Table  5-13  are  function  dependent  arguments. 

5.11.1    F$FNC,  the  MACRO-11  Function  Code 

Table  o-14  lists  the  MACRO  11  function  codes  for  the  different  Form  Driver 
calls  and  notes  the  corresponding  high  ievel  language  calls. 

In  your  application,  you  should  always  refer  to  the  functions  by  the  specified 
symbols,  in  order  to  ensure  compatibility  with  future  versions  of  the  software. 

Table  5-14:     MACRO-U  Function  Codes  and  Meanings 


Function 
Code 


.Meaning 


FC$ALL 
FCSANV 

Fr$(M..S 
F( '.*('. SH 
F("SI)AI' 

F(\«;(;Kr 

F(\S('.S(' 

FCSLST 

FCSOF'N 

FC.'fPAl. 

F('.$F'S(^ 

FC$inT 

F(  .$KAI, 

F('$H'rN 

F('$SH() 

F('$SPF 

FCHSPN 

F($rRM 


FfJKTAL  (let  the  responses  hir  all  fields. 

FdKTAF  (let  the  response  tor  any  field  that  the  user  inputs. 

FI,('1A).S  Close  torni  library. 

FCLR.SH  Clear  the  entire  screen  and  show  the  specitied  form. 

FID.ATA  &  FN!'\'I'.\        Cet  named  data  by  index  or  by  name. 

FCiK'I"  (let  the  response  (or  the  si)e(itied  field. 

FINl.N  Cet  the  lurreni  line  of  a  scrolled  area. 

FPITI,  Output  data  to  last  line  of  flisplay. 

FlA)PKN  Open  torm  library. 

FFH'TAL  Output  data  to  ail  fields. 

FOl'TLN  Output  data  to  the  current  line  of  a  scrolled  area. 

FPrr  Output  data  to  a  specified  field 

FRKTAl.  Return  the  ((intents  of  all  fields. 

FRKTN  Return  the  contents  of  the  specified  field 

FSHOW  Show  the  specified  fortn. 

FSl'OFF  Turn  supervisor  i>nl\  mode  oft. 

F.SPON  Turn  supervisor-only  mode  on 

FI'FT  I'roeeHB  fi«  d  terminator. 
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5.11.2    F$REQ,  the  Required  Arguments  List  Pointer 

Table  5-15  lists  the  contents  of  the  required  argument  list  that  FSKEQ  must 
point  to. 

Table  5-15:    Required  Argument  List  Offsets  and  Meanings 


Offset 


Meaning 


F$STS  Oru'-woni  status  block  pointer. 

F$CHN        One-won!  chiuiiiel  lunnlnT  (UN)  lor  torm  I/O. 

FSIMP  One-word  pointer  to  the  impure  area  provided  for  the  Form  Driver, 


(F$RSIZ  is  the  size  in  bytes  ot  the  required  arguments  list.) 

^'ou   must   use  the  $FI)VDF  macro  to  define  F$RSIZ  at   assembly  time. 
FSRSIZ  should  be  used  to  allocate  space  for  the  required  arguments  list. 


5.11.2.1  FSSTS,  the  Status  Block  Pointer  —  This  word  points  to  a  2-word 
status  block  that  the  P\)rm  Driver  maintains  for  each  active  call.  The  first 
word  of  the  status  block  reflects  the  status  of  a  call  to  the  Form  Driver  as 

follows: 

>0  -  Successful  completion 
<0  -  Error  encountered 

Table  5-1  in  Section  5.1.1  lists  the  MACRO- 11  status  codes  and  their  mean- 
ings. 

Your  MACRO  11  application  should  always  use  the  global  symbols  listed  in 
Table  5-1  in  order  to  ensure  compatibility  with  future  versi(ms  of  the  soft- 
ware. Values  are  also  given  for  each  symbol  only  because  it  is  not  possible  to 
refer  to  the  global  symbols  from  high-level  language  programs. 

If  the  first  word  of  the  status  block  contains  FE$10L  or  FE$IOR.  the  code 
corresponding  to  the  specific  error  is  returned  in  the  second  word.  See  RMS  or 
FC\S  document  at  i(m  for  a  list  of  these  error  codes.  (MACRO  tasks  may  use 
either  RMS  or  F(\S.  depending  on  which  one  you  have  configured  vour  version 
of  the  Form  Driver  to  use.) 


5.11.2.2    FSCHAN,  the  Form  Library  Channel  Number  —    Phis  word  contains     I 
the  channel  number  (Ll'X)  information  that  the  Form  Driver  uses  to  access  a 


form  librarv. 


5.11.2.3  F$IMP.  the  Impure  Area  Pointer—  This  word  points  to  the  beginning 
of  the  impure  area  available  to  the  Form  Driver.  The  impure  ;'rea  is  used  to 
store  information  pertaining  to  the  current  form  and  operator  responses  in  the 
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context  of  that  form  The  first  word  of  the  impure  area  must  contain  its  total 
length  in  bytes.  Roth  the  Form  Editor's  form-wide  attributes  questionnaire 
and  the  listing  of  your  form  that  the  Form  Utility  (FUT)  produces  in  response 
to  the  /FD  option  tell  you  the  length  of  the  necessary  impure  area. 

In  order  to  preserve  the  context  of  a  form,  the  impure  area  pointer  must  be  the 
same  for  all  calls  to  the  Form  Driver  that  refer  to  that  form.  Your  program 
may  not  modify  the  impure  area,  which  is  reserved  for  use  by  the  Form  Driver. 

5.11.3    Function-Dependent  Arguments 

For  each  function  code,  a  different  set  of  function  dependent  arguments  may 
be  required.  In  the  file  descriptions  of  each  call  in  Chapter  6,  the  required  and 
optional  arguments  are  listed  in  full. 

Table  5-16  summarizes  all  of  the  MACRO-U  function  dependent  arguments 
and  the  following  sections  describe  them  in  detail. 

5.11 .3.1  F$NAM,  the  Name  Pointer  —  This  argument  points  to  various  names; 
which  name  depends  on  the  call  it  is  associated  with. 

In  a  call  to  open  a  form  library,  F$NAM  on  input  contains  a  pointer  to  the  file 
specification  for  the  form  library.  The  file  specification  must  be  an  ASCII 
string  terminated  with  a  null. 

In  a  call  to  display  a  form,  F$NAM  on  input  contains  a  pointer  to  a  6-byte 
ASCII  form  name.  The  name  must  be  left-justified,  with  unused  positions 
blank-filled. 

In  a  call  that  requires  a  field  name,  F$NAM  points  to  the  6-byte  ASCII  field 
name  associated  with  the  field  when  the  form  was  defined. 

In  a  call  to  get  named  aata,  F$NAM  points  to  a  6-byte  ASCII  data  name  that 
you  specified  by  means  of  the  Form  Editor. 

5.11.3.2  F$NUM,  the  Line  Number  and  Field  Index  —  F$NUM  may  contain 
two  kinds  of  information,  depending  on  whether  the  call  displays  a  form  or 
requires  a  field  name. 

In  a  call  to  display  a  form,  F$NUM  on  input  contains  a  line  number  from  0  to 
2'A  specifying  the  line  on  the  screen  at  which  the  form  is  to  begin  when  dis- 
played. 

In  calls  that  require  a  field  name,  F$NIjM  is  used  to  pass  a  field  index 
identifying  the  specific  field  between  the  P'orm  Driver  and  the  application 
task.  The  field  index  is  a  positive  integer  specifying  the  element  referred  to  for 
a  field  defined  as  an  array.  F'or  fields  that  are  not  defined  as  arrays,  the  Form 
Driver  ignores  the  index  value  and  returns  it  to  the  application  task  as  1. 

5.11.3.3  F$VAL,  Data  Value  Pointer  —  In  a  call  to  output  data  (to  a  specified 
field,  to  all  fields,  or  to  the  last  line)  F$VAL  on  input  contains  a  pointer  to  the 
data  to  be  displayed.  But  if  the  corresponding  length  of  data  (F$LEN)  is  zero, 
the  Form  Driver  ignores  P'$VAL  and  uses  default  values. 
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On  return  from  a  call  to  get  data  (get  a  field,  get  any  field,  get  all  fields,  return 
a  specified  field  or  all  fields,  or  get  named  data),  $FVAL  contains  a  pointer 
into  the  Form  Driver  impure  area  to  the  data  requested. 

5.11.3.4  F$LEN,  the  Data  Length  —  You  must  provide  the  data  length  in  bytes 
for  all  calls  to  output  data.  The  Form  Driver  uses  a  length  greater  than  zero  as 
the  length  of  the  data  to  output.  The  F$VAL  argument  points  to  this  data. 

The  Form  Driver  uses  a  length  less  than  zero  as  an  indicator  that  the  data 
ends  with  a  null.  See  descriptions  of  individual  calls  for  use  of  a  length  of  zero, 
which  specifies  that  default  values  are  to  be  used. 

For  all  calls  to  get  data,  the  Form  Driver  returns  the  data  length  in  bytes  in 
F$LEN.  Responses  returned  to  the  calling  task  are  always  the  length  of  the 
field  (minus  field-marker  characters)  and  are  blank-filled  or  zero-filled  ac- 
cording to  the  field  definition. 

5.11.3.5  F$TRM,  the  Field  Terminator  Code  —  F$TRM  is  one  word  in  which 
the  Form  Driver  returns  to  your  task  an  integer  code  for  the  key  that  the 
operator  used  to  terminate  a  field  entry.  The  argument  is  also  input  for  the 
FPFT  call. 

Table  5-2  in  Section  5.2.1  summarizes  the  field  terminator  keys,  codes,  and 
meanings.  Table  5-14  summarizes  the  codes  for  the  alternate  keypad  mode 
terminators.  Values  of  the  terminators  are  given  for  use  by  high  level  language 
tasks,  which  cannot  refer  to  global  symbols.  These  are  also  the  terminators 
that  the  FPFT  call  processes. 

5.11.4    Keyword  Encoded  Macros 

In  order  to  simplify  the  interface  to  the  Form  Driver  for  the  MACRO-U 
programmer,  the  software  provides  the  following  keyword  macro  in  the  macro 
library  FMSMAC.MLB: 

$FDi.'       ARG  »FNC  >REO  tNAM  »NUM  »TRM  >i,'AL  »LEN 

Table  5-16  summarizes  the  requirements  and  meanings  of  the  keywords  and 
shows  the  relationships  between  the  keywords  on  input  and  the  global  offsets 
for  function  dependent  arguments  on  output.  The  high  level  language  argu- 
ments are  also  listed  in  Table  5-16  to  show  the  correspondence  between  them 
and  the  MACRO-U  counterparts. 

Table  5-16:    Summary  of  Arguments,  Keywords,  and  Offsets  for  High- 
Level  Language  and  MACRO- 11  Form  Driver  Calls 


High-Level 

MACRO- n 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Requirement  or  Value 


Inputs 


ARC. 
HVM 


A  pointer  to  the  ArKtinient  List. 

A  pointer  to  the  Required  Arj{iiments  List. 

(continued  on  next  page) 
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Table  5-16  (Cont.): 

Summary  of  Arguments,  Keywords,  and  Offsets  for  High 
Level  Language  and  MACRO-11  Form  Driver  Calls 

High-Level 

MACRO-11 

^P 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Requirement  or  Value 

CHAN 

*  None 

A  channel  number  lor  a  form  library  file. 

FID 

NAM 

A  field  name  or  a  named  data  label.  6  char- 
acters long,   including  padding  (for  FOR- 
TRAN IV  and  FORTRAN  IV-PLUS.  add  a 
NULL  byte  also).  For  MACRO-11  only  a 
pointer   to   a   fi-byte   ASCII   field   name  or 
named  data  label.  To  specify  a  scrolled  area, 
u.se  the  name  of  any  field  in  the  scrolled 
area. 

FIDX 

NliM 

A  field  index  for  the  specified  field  (when  the 

field  is  indexed)  or  the  index  for  a  named                  ^^^ 

data  value.                                                                         ^^V 

LEN 

(An  input  value  for  MACRO-11  only)  the 
total  length  of  the  data  to  be  displayed.  The 
value  must  be  -1  for  ASCIZ  strings  and  I)  for 
restoring  default  values  or  clearing  the  last 
line  of  the  screen. 

FLNM 

NAM 

A     form     library     file     specification.     For 
MACRO-11  only,   a  pointer  to  an  ASCIZ 
form  library  file  specification.                                            ^^^ 

fnamf: 

NAM 

A  form  name,  6  characters  long,  including                   ^^^ 
padding  (for  FORTRAN  IV  and  FORTRAN 
IV-PLUS,    add    a    NULL   byte   also).    For 
MACRO-11  only  a  pointer  to  a  (i-byte  ASCII 
form  name. 

FVAL 

VAL 

As  an  input  value,  the  single  value  or  the 
concatenated  values  to  be  displayed: 

•  in  a  field.                                                                         ^^ 

•  in  the  top,  bottom,  or  current  line  of  a                   ^^B 
scrolled  area.                                                                      ^^^ 

•  in  the  last  line  of  the  screen. 

•  in  an  entire  form. 

IMPURE 

*  None 

The  name  of  a  subscripted  variable  (or  ar- 
ray) of  bytes  for  the  impure  area. 

LINK 

NUM 

The  explicit   starting  line  number  for  the 
form,  overriding  the  line  number  assigned 
with  the  Form  Editor. 

tp:rm 

TRM 

As  an  input  value,  the  numeric  code  for  the 
terminator  that  the  Form  Driver  is  to  pro- 
cess. 

Outputs 

[The  Status  Code  is 

set  for  all  calls.  Most 

calls  are  proce.ssed  by  the  Form  Driver,  and  for                    ^^ 

these  (with  MACHO 

11  only)  RO  points  t( 

)  the  Argument  List  when  the  call  processing  is                   ^^^ 

complete. 1 

(continued  on  next  page)                  ^^^ 
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Table  5-16  (Cont.): 


Summmary  of  Arguments,  Keywords,  and  Offsets  for  High- 
Level  Language  and  MACRO- 11  Form  Driver  Calls 


High-Level 

Language 

Argument 

Abbreviation 


MACRO-li 

Keyword 

or 

Offset 


Requirement  or  Value 


FIU 


FIDX 


F$NAM(RO) 


F$NUM(RO) 


A  named  data  label  or  the  current  field 
name.  For  MACRO- 11  only,  a  pointer  to  a 
named  data  label  or  data  name. 

A  field  index. 


FLEN 


F$LEN(RO) 


FVAL 


TERM 


STATUS 
STAT2 


F$VAL(RO) 


F$TRM(RO) 


*  None 

*  None 


For  the  FLEN  hisjh-level  language  call,  the 
length  of  a  specified  field  (not  the  length  of 
the  data  the  field  contains).  For  MACRO-1 1 
calls,  the  total  length  of  the  fields  for  which 
values  are  returned  by  the  Form  Driver, 
such  as: 

•  a  named  data  value. 

•  a  single  field. 

•  all  fields  in  one  line  of  a  scrolled  area. 

•  all  fields  in  a  form. 

A  named  data  value,  a  single  field  value,  or 
a  concatenated  string  that  is  composed  of 
several  field  values  (including  padding  when 
a  value  is  shorter  than  its  field).  For 
MACRO-11  only,  a  pointer  to  the  value  or 
string  in  the  impure  area. 

The  numeric  code  for  the  key  that  the  opera- 
tor used  to  terminate  input: 

•  in  a  field. 

•  in  a  line  in  a  scrolled  area. 

•  in  an  entire  form. 

A  numeric  code  for  the  completion  status  of 
the  last  call  that  was  executed. 

A  numeric  RMS  or  FCS  status  code  for  de- 
tailed information  when  the  STATUS  value 
is  -4  or  18  (for  MACRO-ll,  the  equivalent 
codes  are  FE$IOL  and  FE$10R). 


For  MACRO- 11  only,  the  channel  number  and  pointers  to  the  impure  area  and  status  block 
must  be  specified  in  the  Required  Arguments  List. 


The  $FDV  macro  should  be  used  in  accordance  with  the  keyword  caUing 
convention  of  MACRO-11.  The  argument  names  correspond  to  the  last  three 
characters  of  the  global  argument  list  offsets  defined  by  the  Form  Driver* 

The  information  that  follows  should  enable  you  to  use  the  $FDV  macro  in 
most  instances.  For  further  details  about  calling  macros  with  keyword  argu- 
ments, see  the  PDP-ll  MACRO- 1 J  Lon^ua^r  Reference  Manual  or  the 
lAS/RSX- 1 1  MA CRO  1 1  Language  Reference  Manual.  | 
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All  arfjuments  to  the  $FDV  macro  must  be  in  the  form  of  instruction  source 
operands  to  be  used  in  MOV  instructions  on  the  source  operand  side  as  shown 
below: 

MOU      ar^, destination 

The  destination  of  all  the  arguments  is  either  RO,  in  the  case  of  ARG,  or 
F$xxa:(RO)  in  the  case  of  all  other  arguments,  where  jf.tx  is  the  name  of  the 
argument.  Any  arguments  that  do  not  appear  in  the  macro  call  are  not 
changed  in  the  argument  list  by  the  macro  expansion. 

Since  the  list  of  arguments  to  the  macro  may  be  quite  long,  a  single  call  to  the 
Form  Driver  may  be  broken  up  into  several  calls  to  the  macro.  If  the  FNC 
argument  specifying  the  function  code  is  missing,  the  call  to  the  Form  Driver 
is  not  generated,  and  the  next  call  to  the  macro  can  fill  in  further  arguments. 
Argument  blocks  should  be  built  at  execution  time  or  by  symbolic  means  at 
assembly  time. 

The  following  macro  call  loads  the  required  arguments  list  pointer  into  the 
argument  list.  Loading  the  pointer  normally  needs  to  be  done  only  once  in  a 
program. 

$  F  D  I,'       A  R  G  =  arglst,  R  E  0  =  req  1st 

As  a  result  of  this  call,  RO  points  to  the  specified  argument  list.  The  Form 
Driver  is  not  called  by  the  macro  call. 

The  following  variations  on  a  call  to  the  Form  Driver  to  write  data  to  a 
specified  field  (FPUT)  illustrate  the  syntax  of  the  $FDV  macro: 


Example  1 


•  MCALL  $FDi.'  »*FDi.'DF 
$FDUDF 


DEFINE  ARGUMENT  LIST 
SIZES 
(F$ASIZ  AND  F$RSIZ) 


5  Initialize  required  a  r  d  u  m  e  i"i  t  s  list 

MQi.'      »REOLST»RO      ;  REOU  I  RED  ARl^UMENTS  L  I  ST 

;  POINTER 

M0>.'      «STAT  »F$STS(RO) 
;  STATUS  BLOCK  POINTER 

MOV     «tl  »F$CHN(RO)    ;  LIBRARY  CHANNEL  NUMBER 

MO>J     ttlMPURE  »F$IMP(RO) 
;  IMPURE  AREA  POINTER 

$FD>.'    ARG  =  »ARGLST  .REO  =  «REOLST 
;  PUT  REQ  ARG 

;  LIST  PTR  IN  ARG  LIST 

$FD>.'    ARG  =  «ARGLST  •FNC  =  PUT  .UAL  =  «BUFFER  .LEN  =  DATLN  f 
NAM  =  »FLD1  »NUM  =  »»1 
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In  this  call,  the  argument  list  is  ARGLST,  the  function  is  FC$PUT,  the  data 
to  output  is  in  BUFFER,  the  data  length  is  in  DATLN,  the  field  name  is  in 
FLDl,  and  the  index  is  1.  The  following  data  are  associated  with  the  call. 


isiz  =  102a. 

BUFFER:  .ASCI  I 

DATLN:   .WORD 

FLDl:    .ASCII  /FIELDl/ 

ARGLST:  .BLKB   F$ASIZ 


/TEN  CHARS'^/ 
10. 


REQLST:  .BLKB   F$RSIZ 


IMPURE:  .WORD 
.BLKB 


STAT 


ISIZ 
ISIZ-2 


.  B  L  K  W 


DATA 
LENGTH  OF  DATA 
FIELD  NAME  (G  CHARS) 
ALLOCATE  SPACE  FOR 
ARGUMENT  LIST 
ALLOCATE  SPACE  FOR 
REO  ARG  LST 

SIZE  OF  IMPURE  AREA  IN  BYTES 
THE  IMPURE  AREA 

;2  WORD  STATUS  BLOCK 


Example  2 

The  call  in  Example  1  may  be  broken  into  two  lines  as  follows: 

$FDU       ARG  =  ttARGLST  tUAL  =  «BUFFER  tLEN  =  DATLN 
$FD>.'       FNC  =  PUT  .NAM  =  ttFLDl  »NUM  =  «1 

After  the  first  call  to  the  macro,  the  Form  Driver  is  not  called  because  the 
function  code  (FNC^PUT)  is  not  included.  It  it;  the  second  call  to  the  Form 
Driver  that,  in  addition  to  providing  values  for  further  arguments,  calls  the 
Form  Driver. 

Example  3 

In  the  following  example  of  an  FPUT  call  below,  RO  is  assumed  to  point  to  the 
argument  block. 

1.  The  field  name  is  in  FLDl. 

2.  The  index  is  in  R2. 

'].    The  data  to  output  is  pointed  to  by  RI. 
4.    The  length  is  pointed  to  by  RM. 
.5.    R',i  is  advanced  by  the  call. 

$FDV   FNC  =  PUTtNAM  =  »FLDl,NUh  =  R2  »i.'AL  =  Rl  »LEN=  (R3)  + 

This  way  of  issuing  the  macro  call  is  an  alternative  to  those  shown  in  the  first 
two  examples. 

Chapter  H  describes  each  call  to  the  Form  Driver  in  detail. 
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5.11.5    Special  Information  for  I/O  from  a  MACRO-11  Program 

A  MACRO- 

11  program  may  use  either  RMS  or  FCS.  The  program  must                ^^ 

initialize  FCS  before  callinf<  the  Form  Driver  it  media  resident  forms  are  used.                ^^ 

(See  the  RSX-llM  I/O  Operations  ManuaL  Chapter  2  for  details  or  the 

1 

lAS/RSX-Il 

I/O  Operations  Reference  Manual.)  If  RMS  is  chosen,  the  pro- 

gram  must 

initialize  RMS  with  a  call  to  the  $INIT  or  $INTTIF  macros  if 

media  resident  forms  are  used. 

1 

On  RSX-llM/M-PLUS  systems,  to  avoid  loss  of  typeahead  in  MACRO  11 

programs  using  the  Form  Driver,  attach  the  terminal  with  the  QIO  system 

directive. 

Example:  OIOW$S  «  10.  ATT  »«5  .«5 

5.11.6    Program  Sections  Used  by  FMS 

The  following  PSECT  names  are  reserved  for  use  by  FMS.                                              ^^^ 

PSECT 

Usage 

$.$FMS 

Task  specific  data  and  buffers 

$$FMSV 

Offsets  to  vector  area 

$$FMSB 

Offsets  to  buffer  descriptor 

$$FMS1 

Data  areas  for  form  driver                                                                                 _ 

$FIDX$ 

Memory  resident  form  index                                                                           ^^^ 

$FIDY$ 

End  of  memory  resident  form  index 

$FORM$ 

Memory  resident  form  descriptions 

.FDV. 

Form  driver  and  support  code 

$FDARC 

Argument  list  definitions 

$RQARC, 

Required  argument  list  definitions                                                                flB 

$FNCOD 

Function  code  definitions 

$SYCOD 

Success  code  definitions 

$LNCOL 

Line  column  definitions 

$FLDSC 

Field  descriptor  offsets 

$IMPHD 

Impure  area  header  offsets 

$HLLDFN 

High-level  language  call  defmitions 

$HI.I. 

High  level  language/FDV  Interface 

.ERR. 

Error  messages 

.DBC. 

Debug  error  messages                                                                                       ^^k 
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Three  PSECTs  are  used  to  keep  information  about  memory  resident  forms. 

$FIDX$    Form  Index 
$FIDY$    End  of  Form  Index 
$FORM$    Form  Descriptions 

A  pointer  in  the  Form  Driver  data  area  (FDVDAT)  points  to  the  form  index 
PSECT  $FIDX$.  FDVDAT  must  be  the  first  contribution  to  this  PSECT. 
That  is,  it  mist  be  referenced  in  the  task  build  command  before  any  of  the 
memory  resident  forms.  PSECTs  must  be  ordered  such  that  $FIDX$  and 
$FIDY$  are  adjacent.  This  is  normally  the  case  since  PSECTs  are  normally 
ordered  alphabetically. 

Any  of  these  PSECTs  may  be  in  overlays,  but  $FIDX$  and  $FIDY:  are  nor- 
mally in  the  root.  It  is  quite  reasonable  to  place  forms  in  overlays,  l  e  index 
entries  will  be  pulled  into  the  root  since  $FIDX$  and  $FIDY$  have  he  GBL 
attribute. 

5.11.7    Form  Driver  Conditionals 

All  Form  Driver  conditionals  are  in  the  file  FSYCND.MAC.  The  values  of  the 
following  conditionals  are  set  by  the  configuration  procedure. 

Symbol       Default     Meaning 


BUFSSB 


Buffer  size  in  blocks. 


DRB$N  1  Number  of  directory  buffers. 


FDB$N  1  Number  of  form  libraries  which  can  be  open  simultaneously. 


RMSI$0 


0  for  FCS 

1  for  RMS 


Terminal  support  code  varies  for  the  systems  which  FMS  supports.  This 
conditional  selects  the  terminal  service  required. 

Symbol       Value     Meaning 


TIOT$P  0         RSX-llM  Half  duplex  driver  (V.S.I). 


1  RSX-llM,  M+  Full  duplex  driver. 


Reserved. 


Reserved. 


The  default  is  1. 

The  Form  Driver  uses  .several  conditionals  for  internal  processing  of  event 
Hags  and  I/O  management.  The  conditionals  and  their  default  values  are 
listed  below. 
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Symbol       Default     Meaning 

RESL$B  0  FDVDAT  conditional  data  and  offsets. 

1  Library  offsets. 


2  Data  only  for  task. 


IOE$F  32  Event  flag  for  form  library  I/O. 


TLU$N  5  Terminal  LUN. 


TEF$N  31  Terminal  output  event  flag. 


TIEF$N  30  Terminal  input  event  flag. 


5.11.8  Event  Flags 

The  terminal  event  flags  (TEF$N  and  TIEF$N)  are  selected  to  not  interfere 
with  event  flags  used  by  the  task  for  other  purposes. 

5.11.9  Building  a  MACRO-11  Program 

When  assembling  MACRO-11  programs,  include  the  appropriate  macro  li- 
brary for  your  system  in  the  command  line  to  resolve  MACRO-11  definitions 
for  $FDV  and  other  FMS  macros: 


FMSMAC/ML 

LB: [  1  .  1  ]  FMSMAC/ML 


for   RSX-llM/M-PLlIS   systems 
for   IAS  svstems 


o 


The  following  TKB  command  file  illustrates  how  to  task  build  a  MACRO-11 
program. 

For  RSX-llM  and  RSX-llM-PLUS: 

MACTKB.CMD 

TasK  Build  the  Macro  uersiori  of  the  DEMO  application  ? 

MACDEM  fMACDEM/-SP  =  MACDEM .FDVLIB/LB 

/ 

UNITS=7 

MA)!BUF  =  512 

// 

i 
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For  IAS: 


MACTKB.CMD 

TasK     Build     the    Macro    i.iersion     of     the    DEMQ 
appl  icatiori 

[11.1 IGDMACDEM  .[11  .11G]MACDEM/-SP=[11  .11G]MACDEM.LB:C1  .1 ]FDVLIB/LB 

/ 

UNITS=7 

MA>(BUF=512 

// 

• 

The  following  command  file  illustrates  task  building  (linking)  a  MACRO  task 
using  the  DCL  (PDS)  LINK  command  on  IAS: 


!  MTASK.CMD 


Build  a  MACRO  tasK 


LINK/MAP:MTASK.LB:[1  .IIFDULIB/LIB  MTASK 

I  Form  Dnwer  library  -  FDULRM.OLB  for  RMS  support 
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Chapter  6 

Form  Driver  Calls 


A  flexible  set  of  Form  Driver  calls  provide  functions  that  display  forms,  dis- 
play data  in  fields,  and  handle  terminal  input.  (Additional  calls  are  provided 
for  high-level  language  programs  only.)  The  descriptions  below  show  what 
each  call  does,  what  input  arguments  it  requires,  and  what  output  it  returns 
to  your  task.  For  each  call,  syntax  in  high-level  languages  and  MACRO-11  is 
indicated. 

See  Chapter  5  for  information  on  each  programming  language. 

6.1    FCLRSH  —  Clear  Entire  Screen  and  Display  Form 

The  Form  Driver  clears  the  entire  screen  and  displays  the  specified  form  as 
described  under  FSHOW. 

BASlC-Pl.US-2  and  FORTRAN  Call 

CALL  FCLRSH( fnamUine]) 

COBOL  Call 

CALL   "FCLRSH"   liS  I  HQ  frmmlline]. 

MACRC  11  Call 

$  F  D  >.'  A  R  G  =  n  r^  Is  ^  F  N  C  ■  C  S  H  .  R  E  Q  =  rcc/  /.s  f ,  N  A  M  -  fo  nn ,  N  1.1  K  ^  ^  I  in  c 

Inputs  and  Outputs 


# 


High-T,evel 

MACRO-11 

i.unguaKe 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Requirement  or  Value 


Snputs 


KNAMK 
LINK 


AH(; 
HVAi 
NAM 

Nl'M 


Outputs 


None. 


None. 


A  pointer  to  tho  Arsuiiu'nt  List. 

A  pointer  to  the  Required  Arguments  Li.st. 

A  tortn  nanif.  Kor  MACRO  11  only,  a 
pointer  to  a  ti-hyte  tbnn  naiiie. 

The  explicit  starting  line  number  tor  the 
lorm,  overriding'  the  line  number  assigned 
with  the  Form  Kditor. 


The  status  code  is  set.  For  MACRO   1 1  only. 
R(t  points  to  the  Argument  List. 


(i-l 


Returned  Status  Values  and  Codes 


Status  Value 

High-Lcvcl 

Status  Code 

Languages 

(MACRO-ll) 

1 

Fs$si!r 

-  6 

FKSICH 

-  7 

FK$FrH 

-  8 

KK$FHM 

-  9 

FK$FNM 

-10 

FK$LIN 

-18 

FK.SIOK 

-20 


-21 


Meaning 


iKine 


none 


SiK'cessrul  completion 

invalid  channel  number  specified 

Form  library  not  open  on  specified  channel 

Invalid  form  definition 

Specified  form  does  not  exist 

Invalid  (irst  line  number  to  display  form 

Krror  encou^-^tered  reading  form  library  (an  FCS  or 

HMS  system  error  code  that  i)rovides  more  detail 

can  be  found  with  the  FSTAT  call  and  is  returned 

in  the  second  word  of  the  Status  Block) 

(For  hi{{h-level  lanfjua^e  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 


6.2    FGCF  —  Return  the  Current  Field  Name 

The  FdCP'  call  does  not  call  the  Form  Driver.  It  merely  returns  arjjuments 
trom  the  Form  Driver  argument  block.  FGCF  is  to  be  used  in  conjunction  with 
the  FdET  call  to  allow  immediate  processing  of  fields  and  immediate  feed- 
back to  the  terminal  operator  (as  well  as  implementing  scrolling.) 

In  a  high-level  language  task,  this  call  must  follow  a  call  to  process  a  field 
terminator  if  you  wish  to  access  the  name  of  the  new  current  field  and  its 
index  value. 

There  is  no  MACHO-  1 1  equivalent  for  this  call. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FGCF  (fidlfidx]) 

COBOL  Call 

CALL   "FGCF"   USING  fidlfidx]. 


Inputs  and  Outputs 


High-Lovel 

MACRO  II 

Language 

Keyword 

.Argument 

or 

Abbreviation 

Offset 

Inputs 

None. 

„ 

Requirement  or  Value 
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Outputs 

FID 

FIDX 
Returned  Status  Values  and  Codes 


(All  niiipni  value  lur  hitihlevfl  lati^'uam's 
niiK  I  'I'lic  lifUl  name  Inr  tlii'  currciil  ticld. 

lAii  niitpui  \aliic  t(ir  hi^h-lcvcl  laii^-ua^io 
niiK  I  The  lield  index  lor  the  eurreiit  tield 
(uhi'ii  that   tield  i-  ati  indexed  lieldl. 


Status  Value 

High-I-evel 

Status  ("ode 

Languagos 

(MACRO   11 

1 

Fs.ssrc 

-20 

none 

-21 

none 

-22 

none 

Meaning 


Siu-ce^stul  eninpleliun 

I  For  hi^'h-k'vel  lan^'uage  |)rouratns  only) 

W'ronK  niiniher  ot  art;utnents  in  call 

(For  hit;h  level  lan^Mia^e  prnyrain>  nnlyl 

Impure  area  not  yv\   inil  iali/.ed 

I  MASK'   \'\.\'S   1^   (inl\i    Returned    siring;    i>    longer 

tlian  the  deelared  variable  length 


6.3    FGET  —  Get  the  Value  from  the  Specified  Field 

The  Form  Driver  places  the  cursor  in  the  icitial  position  ol  the  specified  field 
and  accepts  input  by  the  operator  in  that  tield.  (Section  4.2.2.2  describes  the 
initial  cursor  position  for  fields  that  have  ditterenl  attributes.)  When  the 
Form  Driver  returns  control  to  the  application,  the  specified  field  is  the  cur- 
rent field. 

If  the  first  character  of  the  field  name  that  you  specify  is  an  asterisk  ( '),  the 
Form  Driver  sets  as  the  current  field  the  firs;  field  in  the  form  that  is  not 
Display-Only  and  not  within  a  scrolled  area.  The  field  name  and  index  value 
for  that  field  are  returned  to  your  task.  A  hi^h-level  lan^uiage  pro^jram  must 
use  the  FCiCF  call  to  Kft  the  field  name  and  index. 

If  you  do  not  specify  a  field  name,  the  Form  Driver  places  the  cursor  in  (he 
lower  right  corner  of  the  screen  and  waits  for  the  operator  to  press  the  KN'I'KH 
key.  indicating  that  he  or  she  is  ready  to  i)roceed  and  the  field  terminator  code 
0  (<;  .  for  MA(TU)-11  only,  FT$NTH)  is  returned  to  your  program.  This  "'spe- 
cial get"  call  is  a  way  of  synchronizing  the  operation  of  your  program  with  the 
pace  of  the  terminal  operator. 

BASIC-PLUS-2  and  FORTRAN  C»>li 

CALL.  F  G  E  T  f  / r r;  /,  n 77/! .  ftd \ ,  fici.. ,  / 
CALL   FGET 

COBOL  Call 

CALL    "FGET"    US  I  NG  /Vr;/,r<77/(,//(/l,/'/f/.vl. 
CALL   "FGET" 


Kortn  hriver  (."alls     (1  .'{ 


MACRO-11  Call 

$FDi,'          ARG  =  ar,i,'/.s^ 

FNC-GET  tREQ 

-  rcqlst.  M  A  M    fid.  r; ' '  M  ^  id.x                                                ^^ 

Inputs  and  Outputs 

High-Level 

Language 

Argument 

Abbreviation 

MACRO-11 

Keyword 

or 

Offsei 

Requirement  or  Value 

Inputs 

~ 

AR(i 

A  pointer  to  the  Argument  List. 

~ 

REQ 

A  pointer  to  the  Required  Arjjuments  List. 

FID 

NAM 

A    field    name.    P'or    MACRO- il    only,    a 
pointer  to  a  (i-hyte  ASCII  fit'd  name. 

FIDX 

NUM 

A  tield  index  tor  the  specified  field  (\vhen  the                 ^^ 
field  is  indexed).                                                                m^^ 

Outputs 

None. 

N(me. 

The  status  code  is  set.  For  MACRO   11  only. 
Ho  points  to  tne  Arfjument  List. 

— 

FSLENtHO) 

(An  output  value  for  MACRO   11  only)  The 
lenijth  of  the  field. 

F$NAM(RO) 

(An    output    value    for    MACRO-11    only) 

When  the  input  field  name  begins  with  an                ^^^ 

asterisk  (*).  a  pointer  to  the  (vbyte  ASCII                ^B 

name  of  the  field  name  for  the  first  field  that                 ^^ 

is  not  Display  Only  and  not  within  a  scrolled 

area. 

F$NCM(R()) 

(An    output    value    for    MACRO  1 1    only) 
When  the  input  field  name  be;,ins  with  an 
asterisk  (*).  the  field  index  for  the  first  field 
that  is  not   Display  Only  and  not  within  a 
scrolled  area  (when  that  field  is  an  indexed 

K\A1, 

F$VAL(RO) 

The  field  value,  including  padding.                                ^^^ 

IKHM 

F8TRM(R()) 

The  numeric  code  tor  the  key  that  the  oper- 
ator used  to  terminate  input  in  the  field. 

Returned  Status  Vain 

les  and  Codes 

.Status  Value 

High-Level 

Status  Code 

Languages 

(MACRO-II) 

Meaning 

1 

FS.SSIIC 

Successlul  c'(impk'tii)n 

-  6 

FK$irH 

Invalid  rhannel  mimlier  specilied 

-  7 

FK$F('H 

F(. 

m  library  not  o|)en  on  specified  cluinnel 

-11 

FK$FLD 

S|: 

lecilied  field  does  not  exist  (invalid  field  name  or                 ^^^ 

ini 

^y 

6-4 
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-12 


-18 


fe:$nof 

FK$I)SP 
FK$K)H 


20 


21 


'>'? 


none 


mint' 


none 


N(i  lii'lds  (It't'int'd  tor  mirrcnl  Inrm 

(h'\  call  illegal  lor  displas'  oiiK   ficldls) 

Krror  oncountfrcd  reading  lorni  library  Ian  FCS  or 

RMS  system  error  code  that   provides  more  detail 

can  lie  tounci  with  the  FSTA'I"  call  and  is  returned 

in  the  second  word  ot  the  Status  Bloik) 

(For  high-level  language  programs  only) 

Wrong  number  ot  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  >et  initialized 

(BASIC  PLl'S  2   only)    F^'turned   string   is   longer 

than  the  declared  variaiile  length 


6.4    FGETAF  —  Get  the  Value  for  Any  Field 

The  Form  Driver  waits  tor  the  operator  to  respond  to  any  field.  The  operator 
can  move  the  cursor  to  any  field  that  is  not  Display  Only.  The  Form  Driver 
accepts  as  valid  responses  either  the  ENTER  key  alone  or  any  field  terminator 
entered  in  a  fie'd  that  has  been  modified  l\v  the  ojjerator.  The  field  that  is 
entered  becomes  the  current  (ield. 

The  FGETAF  call  is  invalid  for  a  form  that  contains  a  scrolled  area. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FGETAFf/ra/,  trrm,  fid\.fidx\) 

COBOL  Call 

CALL   "FGETAF"   USIHG  fi  nitcnn.fidifidx]. 

MACRO-11  Call 

$ F  D >.'  A rv G  =  amlst.  F  N  C  =  A  N  Y  .  R  E  Q  -"^ rcqlst 

Inputs  and  Outputs 

High-Level  MACRO  II 

Languago  Keyword 

.Argument  or 

Abbreviation  Offset                                           Requirement  or  Value 


Inputs 


AHd 


A  pointei'  to  the  Argument  Fist. 

A  pointer  to  the  Required  Argumi'iils  List 


Outputs 

.None. 

FilJ 
FIDX 


.\one. 
F$NAM(K()) 

F.SNt'MtRO) 


The  status  code  is  set.  For  MACRO  i  1  only, 
R(l  points  to  the  Argument  Fist. 

The  lield  name  tor  the  lield  it:  which  the 
operator  res|)onds.  (For  MACRC  1!  only,  a 
pointer  to  tlu'  (i  b\te  .•\,SC1I  lield  name.) 

'I'he  Held  index  lor  the  field  in  which  the 
operator  responds  (when  that  field  is  an  in- 
(h'Xed  tiel(l). 
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FVAL 


F$LKN(Fi()) 


F$VAL(RO) 


The  leii^'th  oC  the  fii'ld. 


The  field  value,  iiuliidiiig  padding. 


TERM 


F$TRM(R()) 


Returned  Status  Values  and  Codes 


The  mmieric  code  lor  the  i\ey  that  the  oper- 
ator used  to  terniinate  input  in  ihe  field. 


Status  Value 

Hiffh-Level 

Status  Code 

Languages 

(MACRO-11) 

1 

FS.$SLIC 

-  6 

FE.SICH 

-  7 

FE$FCH 

-12 

FE.SNOF 

-i:? 

FE.SDSP 

-18 

FE$10R 

Meaning 


19 

FE$1FN 

20 

none 

21 

none 

22 

none 

Suece.sstul  completion 

Invalid  channel  nuinl)er  speeilied 

Form  lihrary  not  open  on  specified  channel 

No  fields  defined  for  current  form 

(let  call  illegal  tor  display  only  field(s) 

Error  encountered  reading  form  library  (an  FCS  or 

RMS  .system  error  code  that   provides  more  detail 

can  he  found  with  the  FSTAT  call  and  is  returned 

in  the  second  word  of  the  Status  Block t 

Specified  call  invalid  in  current  context  of  form 

(For  high-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 

(BASIC  PLl'S  2  only)    Returned  string   is   longer 

than  the  declared  variable  length 


6.5    FGETAL  —  Get  All  Field  Values 

Beginning  with  the  first  field  in  the  form,  the  terminal  operator  may  move 
about  the  form  and  enter  and  change  values  in  any  fields  that  he  or  she 
chooses.  The  F'orm  Driver  waits  for  the  operator  to  press  the  KNTER  key  as  a 
signal  that  he  or  she  has  completed  the  entire  form.  The  values  of  all  fields  are 
then  returned  to  your  program  as  a  concatenated  string  of  the  default  values 
and  new  entries  that  are  displayed.  Fields  are  returned  in  left-to-right,  top-to- 
bottom  order,  except  when  a  form  contains  vertically  indexed  fields.  See 
Sections  4.1.7  on  the  order  of  return  for  indexed  fields. 

Normally,  when  a  form  includes  fields  with  the  Response  Required  or  Must 
Fill  attribute,  the  fields  must  be  completed  before  the  Form  Driver  will  return 
to  the  program.  Otherwi.se,  a  message  is  displayed,  the  bell  rings,  and  the 
cursor  is  located  at  the  tirst  incomplete  field. 

However,  when  the  program  has  set  the  V'TIOO  to  the  alternate  keypad  mode, 
the  alternate  keypad  mode  terminators  are  always  passed  immediately  to  the 
program.  Section  4.2.2  describes  the  alternate  keypad  mode  feature. 
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The  FGETAL  call  with  no  arguments  only  stores  the  values  for  all  fields  in  the 
Form  Driver  impure  area.  You  can  then  access  the  values  with  the  FRETN  or 
FRETAL  call.  The  calls  are  described  later  in  this  chapter. 

The  FGETAL  call  is  invalid  lor  a  form  that  contains  a  scrolled  area. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL.  FGETALf/rrt/(,^(Tmly 
CALL   FGETAL 

COBOL  Call 

CALL   "FGETAL"   US  I  NG  /rn/l.^crm). 
CALL   "FGETAL" 

MACRO-11  Call 

$  F  D '>'    A  R G  =  arulst,  F  N C  =  A L  L  .  R  E  W  =  rcqlst 

Inputs  and  Outputs 


High-Lcvel 

Language 

Argument 

Abbreviation 


Inputs 


MACRO- II 

Keyword 

or 

Offset 


Requirement  or  Value 


AR(; 

REQ 


A  pointer  to  the  Arfjument  List. 

A  pointer  to  the  Required  Arguments  List. 


Outputs 


None. 


K\"AL 


TERM 


None. 
F.SLEN(RO) 
p:SVAL(R()) 

F.STRMiROl 


The  status  code  is  set.  For  MACRO-11  only. 
RO  points  to  the  Argument  List. 

(An  output  value  tor  MACRO-11  only)  the 
total  length  tor  all  fields  in  the  form. 

The  concatenated  values  for  all  fields  in  the 
torm.  For  MACRO-11  only,  a  pointer  to  the 
concatenated  values  in  the  impure  area. 

The  numeric  code  lor  the  key  that  the  oper- 
ator used  to  terminate  input  in  the  form. 


Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 


1 
6 

7 


Status  Code 
(MACRO-11) 


Meaning 


fs$sl;c 

FE.1iI(^H 
FE.$FCH 


Successful  complel  ion 

Invalid  channel  number  specified 

Form  library  not  ojx'ti  on  specified  chaime 
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-12 

KK.SNOK 

\(i  ticlds  (ieliiu'd  lor  current  form                                                    _ 

-Vi 

KivSDSl' 

(li't  call  ilii>^';i.!  i<<r  display  only  t'ield(s)                                        ^^B 

-18 

KK$IOK 

Krnir  I'luduntered  reading  lorni  library  (an  PCS  or                  ^^^ 
I^MS  system  error  code  that   |)rovides  more  detail 
can  he  found  with  the  KSTAT  call  and  is  returned 
in  the  second  word  ol  the  Status  Block) 

-19 

FK.SIFN 

Specified  call  invalid  in  current  context  of  form 

L'O 

iiDiie 

(For  high-level  language  programs  only) 
VNrong  number  of  arguments  in  call 

21 

IKMU' 

(For  high-level  language  programs  only) 
Impure  area  not  yet  initialized 

-22 

none 

(BASIC   PLCS  2   only)    Returned   string   is   longer 
than  the  declared  variable  length 

6.6 

FIDATA  —  Get  N 

amed  Data  by  Index 

This  call  accesses  named  data  by 

using  the  index  into  the  named  data  rather             ^^ 

than  the  name 

of  the  data. 

w 

BASIC-PLUS-2 

and  FORTRAN  Call 

CALL    F I  DATA! 

fidx.  fvub 

COBOL  Call 

CALL    "FIDATA 

"   USING  fid.x.fral. 

MACRO-11  Call 

^ 

*  F  D  V          A  R  G  ^=  ariilst.  F  N  C    DAT  .RE 

: Q  - reqlst,  N  A M  ^  uO.  N U  M  ^  mm                                                    ^^ 

Inputs  and  Outputs 

High-Level 

MACRO- 11 

l.anBuaKt' 

Keyword 

Argument 

or 

Abbreviation 

OfTset 

Requirement  or  Value 

Inputs 

• 

— 

ARC 

A  pointer  to  the  Argunient  List. 

-- 

RKQ 

A  pointer  to  the  Required  Arguments  List. 

FIDX 

N'CM 

The  index  tor  a  named  data  value. 

NAM 

(An   input    value   tor  MACRO   11   only)   for 
this   call,   the  value  ot   the   NAM   keyword 

must  be  0. 

Outputs 

None. 

Nnm'. 

The  status  code  is  set.  For  MA('I{0    1  1  only, 
Ro  points  to  the  Argument  List. 

K$NAM(K()I 

(An   outpul    value   for   MACRO   11    only)   a 
pointer  to  the  named  data  label  in  the  im- 
pure area. 

" 

K$LKN(R()) 

(An  output  value  for  MACRO  11  only)  The                  ^B 
length  of  the  named  data  value.                                           ^^^ 

(>-8 

Form  Driver  Calls 

FVAL 


F$VAUH()) 


The  named  (ialn  value  tor  the  index  re- 
quested. For  MACHO  11  only,  a  (jointer  to 
the  named  data  value  in  the  im|)ure  area. 


Returned  Status  Values  and  Codes 


Status  Value 

High-Level 

Status  Code 

Languages 

(MACRO!  1) 

1 

Fs$sur 

-15 

FE$DNM 

-20 

none 

-21 

none 

22 

none 

Meaning 


J 


Successful  completion 

Named  data  specified  does  not  exist 

(P'or  high-level  languajje  profjrams  only  I 

Wronj?  number  of  arf^uments  in  call 

(For  hifih-level  language  programs  only) 

Impure  area  not  yet  initialized 

(RASir-PLlJS-2   only  I   Returned  string   is   longer 

than  the  declared  variable  length 


6.7    FINIT  —  Initialize  Impure  Area  for  High-Level  Language 
Tasks 

The  F'INIT  call  specifies  the  space  for  the  impure  area.  The  P'lNIT  call  must 
precede  any  other  Form  Driver  calls  in  a  program. 

For  the  size  of  the  impure  area,  use  the  size  reported  by  the  Form  Fiditor  tor 
the  largest  form  that  your  program  uses,  and  add  64  bytes.  The  high  level 
language  interface  uses  the  first  64  bytes  of  the  impure  area  for  the  argument 
list  for  Form  Driver  calls. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  F  INIT (impure,  sizelstatus]) 

COBOL  Call 

CALL   "FINIT"  USING  impure,  sizelstatus]. 

Inputs  and  Outputs 


High-Level 

MACRO!  1 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Inputs 


IMF'l  RE 


SIZK 
Outputs 


STATUS 


*    None 


*    None 


Requirer,ient  or  Value 


The  name  of  a  subsiripted  variable  (or  ar- 
ray) of  bytes  for  \hv  impure  area. 

The  size  of  the  impure  area. 


A  numeric  code  tor  tlie  i(imi)letion  stati  s  ol 

the  call. 
For  MACRO  11  only,  the  pointers  to  the  impure  area  and  status  block  are  (ontained  in  the 
Required  Arguments  List. 


Kdrtii  Driver  Calls    <>-?♦ 


Returned  Status  Values  and  Codes 


Status  V'aliu' 
U  Ik  h- 1. <'%<•! 
l.anKiia^cs 


Status  ("ode 
(MACRO   11) 


Moaning 


KKslMl' 

IltilU' 


Impure  area  inn  -mall 

I  I'll r  hii;lt-l('\('l  laii^na^f  pni^ram-  nnl\  i 

\S  loiii;  iiumluT  ('I  ai'mimciil-  im  call 


6.8    FINLN  —  Get  Current  Line  of  Scrolled  Area 

Within  the  cuirfiit  line  o!  the  spccilied  scrolled  area,  the  ^^)rITl  I)ri\er  usually 
places  the  cursor  at  the  iiutial  position  ot  the  first  lield  that  is  not  Display 
Only.  Ho\ve\er.  it  the  last  lall  to  the  Form  Driver  was  an  P'l'F'r  call  to  process 
the  ternunator  to  scroll  backward  to  the  previous  field  (\alue  7.  MACHO  11 
global  FTsSPNi.  the  tursor  is  placed  at  the  initial  position  ot  the  last  field 
on  the  line  that  is  not  displa\  onl> ,  The  terminal  operator  may  complete  the 
line  to  his  or  her  sat istact ion.  I'hi'  Form  l)ri\er  then  retin'ns  the  contents  of 
the  line  as  a  concatenated  string  of  field  values. 

BASIC-PLUS-2  and  FORTRAN  Call 

rALL    FTNl.  N^//f/,  li(ii[JiTm]l 

COBOL  Call 

CALL    "FINLN"   \.i3lN^,  fid. fi<il[. term]. 

MACRO-11  Call 

*FD'.'  APG::ari,'/.s/,F  NC  ■  GSC  .REQ    n'(//.s7.iJMM    fid 

Inputs  and  Outputs 


MiKh-l,ovel 

l.anKuago 

.XrKunu'nt 

Abbreviation 


MAC  RO  11 

Keyword 

or 

( )ffsot 


Requirement  or  Value 


Inputs 


KID 


Outputs 


NuiH", 


.\H(i 
HVA} 
.\A.\I 


.\(iIU'. 

K$LKN(1{()) 


.•\  iximtcr  to  the  .-Xr^iimcnl  i.isl. 

.•\  pi.iiiitT  111  the  Hi'ijuucd  .Ar^'Mnu'iils  Li.'^t. 

.\  lifld  naiiif  lor  any  tield  within  the  .^^irolleci 
area  ti.  he  processed.  For  MA''H()  1 1  only,  a 
po.n'er  to  a  (i-luie  ASCI!  tield  name. 


The  statu- code  IN  set.  For  M.ACKO   11  only. 
H(i  points  to  the  Arfiuinent  List. 

(.All  oiiipiit  \ahie  lor  M.ACHO    11  only!  the 
total  leiif;lh  ot  all  lields  in  the  line. 


(J-IO    Fonn  Driver  Calls 


FV'AL 


tp:hm 


F$VAL(R()) 


F$TRM(RO) 


The  values  lor  all  lields  in  the  line,  cmica- 
tenated  from  left  to  ri^'ht.  For  MACHO  11 
only,  a  i)ointer  to  the  concatenated  values  in 
the  impure  area. 

The  numeric  code  ior  the  key  that  the  oper- 
ator used  to  terminate  input  in  the  line. 


Returned  Status  Values  and  Codes 


Status  Value 

High-Level 

Status  Code 

Languages 

(MACRO!  1) 

1 

FS.$SCC 

-  6 

FE$ICH 

-  7 

FE$FCH 

-11 

FE$FLD 

-14 

FE$NSC 

-18 

FE$IOR 

20 
-21 


Meaning 


none 


none 


none 


Successful  completion 

Invalid  channel  number  specified 

Form  library  not  open  on  specified  channel 

Specified  field  does  not  exist  (invalid  field  name  or 

index) 

Specified  field  not  in  scrolled  area 

P>ror  encountered  reading  form  library  (an  FCS  or 

RMS  system  error  code  that   provides  more  detail 

can  be  found  with  the  FSTA  F  call  and  is  returned 

in  the  second  word  of  the  Status  Block) 

(F"()r  high-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 

(BASIC-l'Ll'S  2  only)    Returned  string  is  longer 

than  the  declared  variable  length 


6.9    FLCHAN  —  Set  Channel  (LUN)  for  Form  Library  File 

The  FLCHAN  call  sets  the  channel  (LUN)  to  be  used  to  (»pen  or  access  a  form 
library  tile.  The  FLCHAN  call  must  be  issued  after  the  FINIT  call  and  before 
the  first  FLOPEN  call. 

The  FLCHAN  call  has  two  uses:  it  sets  the  channel  for  the  next  FLOPP'N  call, 
and  it  sets  the  channel  on  which  forms  will  be  accessed  by  FSHOW  and 
FCLRSH  calls.  More  than  one  form  library  file  can  be  open  at  one  time  In- 
using  FLCHAN  to  switch  channels  between  FLOPEN  calls.  P'orms  can  be 
selected  from  one  of  several  libraries  by  using  FLCHAN  to  select  the  desired 
library  before  the  FSHOW  or  FCLRSH  call.  The  library  channel  should  not 
be  switched  until  just  before  the  next  call  to  show  a  form,  since  operator  help 
or  screen  refresh  functions  require  re-accessing  of  the  form  description  for  the 
current  form  that  the  operator  is  using. 

The  channel  named  must  be  legal  for  the  program  and  must  have  been  desig- 
nated as  such  when  the  program  was  built. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FLCHAN  (chan) 


Form  Driver  Calls    6-1 1 


COBOL  Call 

CALL   "FLCHAN"   USING  chnn. 

Inputs  and  Outputs 


Hi^h-I.evel 

MACRO!  1 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Inputs 

CHAN 

*    None 

Requirement  or  Value 


A  channel  number  for  a  form  library  file. 

Outputs 

None. 
For  MACHO-II  only,  the  channel  number  is  specified  in  the  Required  Arguments  List. 

Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 


Status  Code 
(MACRO!  1) 


Meaning 


1 
-20 

-21 


Fs$si;c 

none 
none 


Successful  completion 
(For  high-level  language  programs  only) 
Wrong  number  of  arguments  in  call 
(For  high-level  language  programs  only) 
Impure  area  not  yet  initialized 


6.10    FLCLOS  —  Close  Form  Library 

The  Form  Driver  closes  the  form  library  open  on  the  current  channel  (LUNl 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FLCLOS 

COBOL  Call 

CALL   "FLCLOS"  . 

MACRO-11  Call 

$  F  D  I.'  A  R  G  =  ort'/.sf ,  FNC^CLS.REO-  rcqist 


6-12    Form  Driver  Calls 


Inputs  and  Outputs 


High-Level 

MACRO!  1 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Inputs 


ARG 

rp:q 


Requirement  or  Value 


A  pointer  to  the  Argument  List. 

A  pointer  to  the  Required  Arguments  List. 


Outputs 


None. 


None. 


Returned  Status  Values  and  Codes 


The  status  code  is  set.  For  MACRO- 11  only, 
RO  points  to  the  Argument  List. 


Status  Value 
High-Level 
Languages 


1 

-  6 

-  7 
-20 

-21 


Status  Code 
(MACRO!  1) 


Meaning 


FS$SUC 
FE$ICH 
FE$FCH 
none 

none 


Successful  completion 

Invalid  channel  number  specified 

Form  library  not  open  on  specified  channel 

(For  high-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 


6.11    FLEN  —  Return  the  Length  of  the  Specified  Field 

The  FLEN  call  returns  the  length  of  the  specified  field.  The  high  level  lan- 
guage forms  of  the  call  are  the  only  ones  that  exist.  No  MACRO- 11  equivalent 
is  supplied. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FLENfflcn,  fidlfidx]) 

COBOL  Call 

CALL   "FLEN"   USINQ  flrn.  fidlfidx]. 


Form  Driver  Calls    6-L') 


Inputs  and  Outputs 


High-Level 

MACRO-ll 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Inputs 

FID 
FIDX 

Outputs 

FLKN 


Requirement  or  Value 


A  field  name. 

A  tield  index  tor  the  speeitied  field  (when  the 
field  is  indexed). 


The  field  length. 


Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 


Status  Code 
(MACRO-ll) 


Meaning 


1 
-20 

-21 


FS$SUC 
none 

none 


Successful  completion 
lF'>r  high-level  language  programs  only) 
Wrong  number  of  arguments  in  call 
(P'or  high-level  language  programs  only) 
Impure  area  not  yet  initialized 


6.12    FLOPEN  —  Open  Form  Library 

The  Form  Driver  opens  the  specified  form  library  file  on  the  current  form 
library  channel.  The  channel  (LUN)  must  be  valid  for  the  task  and  not  at- 
tached by  the  program  for  another  use.  Except  for  COBOL  which  uses  LlIN  1, 
LUN  5  is  the  default  used  for  terminal  service  by  the  Form  Driver  and  is 
therefore  not  available  to  your  program.  The  form  library  file  specification 
must  have  the  following  format  (optional  elements  are  enclosed  in  square 
brackets,  but  the  UIC,  if  specified,  must  be  enclosed  in  square  brackets): 

[di'vicc:][l  'IC]filc. typ[: version] 

The  default  file  type  for  a  form  library  file  is  .FLB. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FLOPENr///jmj 

COBOL  Call 

CALL   "FLOPEN"   USING //nr??. 

MACRO-11  Call 

$FDi.'  ARC  =f/rA'/.s/,FNC  -  0  PN  .  REO  -m//,s^  NAM    lib 


6-11    Form  Driver  Calls 


Inputs  and  Outputs 

High-I.cvci 

Language 

Argument 

Abbreviation 

Inputs 


MACRO!  1 

Keyword 

or 

Offset 


Requirement  or  Value 


FLNM 


Outputs 


None. 


AR(; 

KKQ 
NAM 


None. 


A  piiinter  to  the  Argument  List. 

A  jiointer  to  the  Required  Arguments  List. 

A  form  library  file  speciliration.  For 
MACRO  11  only,  a  pointer  to  an  ASCIZ 
form  library  file  specification. 


The  status  code  is  set.  For  MACRO   1 1  only, 
RO  points  to  the  Argument  IJst. 


Returned  Status  Values  and  Codes 

Status  Value 

High-Level  Status  Code 

Languages  (MACRO-11) 


Meaning 


1 

FS$SUC 

■^ 

FE$FSP 

4 

FE$IOL 

5 

FK$FLB 

6 

FE$ICH 

18 

FE$IOR 

-20 
-21 


none 


none 


Successful  completion 

Invalid  file  specification 

Error  encountered  opening  form  library  (an  FCS  or 

RMS  system  error  code  that  provides  more  detail 

can  be  found  with  the  FSTAT  call  and  is  returned 

in  the  second  word  of  the  Status  Block) 

Specified  file  not  form  library 

Invalid  channel  numbei  specified 

Error  encountered  reading  tbrm  library  (an  FCS  or 

RMS  system  error  code  that  provides  more  detail 

can  be  tound  with  the  FSTAT  call  and  is  returned 

in  the  second  word  of  the  Status  Block) 

(For  high-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 


6.13    FNDATA  —  Get  Named  Data  by  Name 

This  call  is  used  to  access,  by  name,  data  that  has  previously  been  associated 
with  a  form  as  named  data.  The  Form  Driver  can  access  the  named  data  that 
is  attached  to  a  form  description  but  does  not  display  the  data  with  the  form. 

You  can  determine  whether  the  FNDATA  call  returns  a  valid  named  data 
value  by  using  the  FSTAT  call.  If  the  FS'l^A'I  call  returns  a  status  value  of 
If),  no  named  data  value  was  found. 


Form  Driver  Calls    6-15 


BASIC-PLUS-2  and  FORTRAN  CaM 

CALL  FNDATArM  fral) 

COBOL  Call 

C  A  L  L   "  F  N  D  A  T  A  "   U  S  I  N  G  fid.  fral. 

MACRO-11  Call 

* F  D '.'  A  R  G  ^ (iri>l.st.  F  N C  -  D  A  T  .  P E  0  - rcqlst,  N  A M    nam 

Inputs  and  Outputs 


High-Level 

MACRO-11 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

inputs 


KID 
Outputs 

None. 


KVAL 


AHd 
NAM 


Niiiie. 
F$LEX(R()) 
FSVAMRO) 


Requirement  or  Value 


A  pointer  to  the  Arfjument  List. 

A  pointer  to  the  Required  Ar^ument-s  List. 

A  named  data  labeL  For  MACRO- 1 1  only,  a 
pointer  to  a  (M)yte  ASCII  named  data  labeL 


The  status  code  is  set.  For  MACRO-ll  only, 
RO  points  to  the  Arf^uinent  List. 

(An  output  value  tor  MACRO  11  only)  The 
lenj^th  ol  the  named  data  value. 

The  named  data  value  (or  the  label  re- 
quested. For  MACRO  11  only,  the  pointer 
to  the  named  data  value  in  the  impure  area. 


Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 


1 
-21 


Status  Code 
(MACRO-ll) 


FS.^SCC 

FK$I)NM 

none 

none 

none 


Meaning 


Successtul  completion 

Named  data  specified  does  not  exist 

(For  hifjh-level  lanjiuage  profjrams  only) 

Wron^  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 

(BASIC  I'LCS  2  only)    Returned   string   is   longer 

than  the  declared  variable  length 


6.14    FOUTLN  —  Output  Data  to  Current  Line  of  Scrolled  Area 

The  Form  Driver  outputs  the  data  that  you  specily  to  the  current  line  of  the 
scrolled  area.  You  identily  the  scrolled  area  by  specilyinji  the  name  of  any 
Held  in  that  area. 


<)-!(»     Forni  Driver  ("alls 


It  the  data  's  too  lon^'  lor  the  liiu'.  the  Form  Driver  retunis  an  error  to  your 
program  and  trupcates  the  data  when  it  is  displayed.  Il  the  (hita  is  too  short 
for  the  line,  deiaiilt  values  are  displayed  lor  ttelds  lor  which  no  data  is  pro- 
vided. If  the  length  ol  the  data  is  zero,  the  Form  Driver  restores  delault  values 
to  all  fields  in  the  current  line  ol  the  scrolled  area. 

The  Form  Driver  does  not  validate  data  output  to  fields  Iroiii  the  ap|)lication 
task.  This  is  true  lor  both  explii'it  output  and  delault  values. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL    FOUTLN(/>f/|./r(f/U 

COBOL  Call 

CALL    "FOUTLN"   US  1  NG  //r/(./rfj/!. 

MACRO-11  Call 

$FD'.'  ARG  =  (;ri.'/>rFNC     Psf  .  Ft'F  Q    n'(//.s7.  tl.-M    //(/. '.'►,!      ial,\yu    Irn 

Inputs  and  Outputs 


HiKh-l.fvel 

l.anKuaKi* 

ArKumont 

Abbreviation 


Inputs 


KID 


K\  AL 

Outputs 

Noiu'. 


MACRO  11 

Keyword 

or 

( )ffset 


AHC, 
NAM 

I.KN 


\AL 


NnlU 


Requirement  or  N'alue 


.•\  pditilcr  i<i  ilu'  .Artruiiu'iil  I-ist. 

.A  immUT  In  ilu'  Ht'()uirt'(l  ArKumeiil>  l.i^<l. 

A  lii'id  iiatiit'  tnr  any  field  within  the  trolled 
area  to  he  processed.  Fur  M.\('K()  1 1  only,  a 
l)iiiiiter  to  a  t; -byte  .•XSCII  field  name 

I. An  input  \aliie  tor  M.ACRO  11  i)m1\  i  the 
total  len>;th  of  the  data  to  l)e  displaved 
(must  he  1  for  ASCI'/  strings  and  0  tor  res- 
toring the  default  \alues  to  all  fields  in  the 
line) 

The  field  valueir^i  to  he  displaved  in  the  i  ur- 
renl  line  ol  the  scrolled  area. 


I'hc  status  code  is  set    Kor  M.ACKO   11  only. 
Ko  points  to  the  .Xryuinent  l.ist. 


Returned  Status  Values  and  Codes 


SttttUN  Value 
HiRh-I-evel 
Lan^uaRes 


1 
II 


Status  Code 
(MACROin 


Ksssrc 

FK.SKLD 


Meaning 


Successful  completion 

Specified  field  does  not  exist  Oiivalid  field  name  or 

index! 


Form  Driver  Cf.lls    (»-17 


-14 
-16 

-20 

-21 


FE$NSC 
FE$DLN 


none 


none 


Specified  field  not  in  scrolled  area 

Data  specified  for  output  too  long  (truncated  by 

Form  Driver) 

(For  high-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

{VoT  high-level  language  programs  only) 

Impure  area  not  yet  initialized 


6.15    FPFT  —  Process  the  Field  Terminator 

The  Form  Driver  processes  the  field  terminator  that  you  specify.  Then,  if  it  is 
valid,  the  Form  Driver  returns  the  name  and  index  for  the  new  current  field  to 
your  program.  In  high-level  languages,  the  FGCF  call  must  be  issued  immedi- 
ately after  the  FPFT  call  to  get  the  name  of  the  new  current  field. 

If  the  field  terminator  specified  is  for  he  ENTER  key,  the  Form  Driver  checks 
the  form  for  Response  Required  and  Must  Fill  fields.  If  the  form  contains  such 
fields  and  the  requirements  are  not  met  for  every  field  in  the  form,  the  status 
code  is  set  to  show  that  the  form  is  incomplete  as  shown  below. 

In  MACRO- 11  tasks,  the  Form  Driver  returns  the  pointer  to  the  name  of  the 
first  incomplete  field  and  that  field's  index  value.  In  high-level  language 
tasks,  the  FGCF  ("Get  the  Name  of  the  Current  Field")  call  is  used  to  obtain 
the  field  name  and  index  value. 

If  the  terminator  relates  to  scrolling,  you  must  provide  the  name  of  a  field  in 
the  call.  The  field  name  identifies  the  scrolled  area  that  the  Form  Driver  is  to 
manipulate.  The  name  of  any  field  in  the  scrolled  area  will  do. 

If  the  field  terminator  is  for  the  TAB  or  Downarrow  key,  your  task  may  also 
specify  data  to  be  displayed  in  the  bottom  line  of  the  scrolled  area  when  the 
area  is  scrolled  forward. 

If  no  data  is  specified  and  the  current  line  is  not  the  bottom  line  of  the  scrolled 
area,  the  cursor  moves  down  one  line  and  that  line  becomes  the  new  current 
line.  If  no  data  is  specified  and  the  current  line  is  the  bottom  line,  the  area  is 
scrolled  up  and  default  values  restored  to  the  bottom  line.  If  data  is  specified, 
the  area  is  always  scrolled  up,  the  data  displayed  on  the  bottom  line,  and  the 
current  line  remains  the  same  line.  If  the  terminator  is  for  the  BACKSPACE 
or  Uparrow  key,  your  task  may  specify  the  data  to  be  displayed  in  the  top  line 
of  the  scrolled  area  when  the  area  is  scrolled  backward.  If  no  data  is  specified 
and  the  current  line  is  not  the  top  line  of  the  scrolled  area,  the  cursor  moves 
up  one  line  and  that  line  becomes  the  new  current  line.  If  no  data  is  specified 
and  the  current  line  is  the  top  line,  the  area  is  scrolled  down  and  default 
values  restored  to  the  top  line.  If  data  is  specified,  the  area  is  always  scrolled 
down,  the  data  displayed  on  the  top  line,  and  the  current  line  remains  the 
same 

If  a  field  terminator  is  not  specified  in  the  call,  the  last  field  terminator 
returned  from  the  Form  Driver  is  processed. 
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FORTRAN  and  BASIC-PLUS-2  Call 

CALL  FPFKtermlfidlfcal]]) 

or 

CALL  FPFT 

COBOL  Call 

CALL   "FPFT"   USING  tenn[,fid[,{val\\. 

MACRO-11  Call 

$FDU  ARG  =  arA'/,sf,FNC-TRM  ,  REQ  =  rt'(//,sMPM  =^^rm.NAM  =//c/.UAL -ra/.LEN  =  /(7J 


Inputs  and  Outputs 

High-Level 

Language 

Argument 

Abbreviation 


Inputs 


FID 


FVAL 


TERM 


Outputs 

None. 


MACRO-n 

Keyword 

or 

Offset 


ARC. 
REQ 
NAM 


LEN 


\AL 
TRM 

None. 

F$NAM(R()) 

F.$NUM(R()) 


Requirement  or  Value 


A  pointer  to  the  Argument  List. 

A  pointer  to  the  Required  Arguments  List. 

(An  input  value  only  if  a  scrolled  area  termi- 
nator is  specified)  a  field  name,  identifying 
the  scrolled  area  to  be  proce.ssed.  Vox 
MACRO-11  only,  a  pointer  to  a  6-byte 
ASCII  field  name. 

(An  input  value  foi  MACRO-11  only  and 
only  if  a  scrolled  area  terminator  is  speci- 
fied) the  length  of  the  data  to  be  displayed 
(must  be  -1  for  ASCIZ  strings  and  0  if  no 
data  is  specified. 

(An  input  value  only  if  a  scrolled  area  termi- 
nator is  specified)  the  field  value(s)  to  be 
displayed  in  the  top  or  bottom  line  of  the 
.scrolled  area. 

A  numeric  code  for  the  terminator  that  the 
Form  Driver  is  to  process. 


The  status  code  is  set.  Vox  MACRO-11  only, 
R()  points  to  the  Argument  List. 

(An  output  value  for  MACRO-11  only)  A 
pointer  to  the  6-byte  AS(TI  field  name  for 
the  current  field. 

(An  output  value  for  MACRO-11  only)  The 
field  index  for  the  current  field  (when  that 
field  is  an  indexed  field). 
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Returnbi  Status  Values  and  Codes 


Status  Value 

High-Lcvel 

Status  Code 

LanRuages 

(MACRO- 11) 

1 

FS$Sl'C 

2 

FS$INr 

-11 

FK$FLD 

-14 

FH$NSr 

-17 

FK$l'TR 

-19 

FE$IFN 

-20 

none 

Meaning 


-21 


none 


Siu'cesslul  completion 

Current  Conn  incomplete 

Specified  field  does  not  exist  (invalid  field  name  or 

index) 

Specified  field  not  in  scrolled  area 

Undefined  field  terminator 

Specified  call  invalid  in  current  context  of  form 

(For  hifjh-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 


6.16    FPUT  —  Output  a  Value  to  Specified  Field 

The  Form  Driver  displays  the  value  in  the  field  that  you  specify  and  stores  the 
value  in  the  impure  area.  If  the  value  to  be  displayed  is  shorter  than  the  field 
for  which  it  is  intended,  the  Form  Driver  right  or  left  justifies  and  zero  or 
blank  fills  the  field  according  to  the  field's  definition.  If  the  value  is  longer 
than  the  field,  the  Form  Driver  truncates  the  value  when  displayed  and  if  the 
Form  Driver  contains  Debug  support,  sets  the  status  code  to  -16. 

If  the  length  of  the  value  to  be  output  is  zero  and  the  field  has  a  default  value, 
the  Form  Driver  restores  the  default  value  to  the  screen  and  the  impure  area. 
If  the  field  has  no  default  value,  the  Form  Driver  clears  the  field. 

The  Form  Driver  does  not  validate  either  the  specified  or  the  default  values. 

FORTRAN  and  BASIC-PLUS-2  Call 

CALL  FPUTf/ro/,  fidifidx]) 

COBOL  Call 

CALL   "FPUT"   USING  /rn/,/((/[.//rf.rl. 

MACRO-11  Call 

$  F  D «.'  A  R  G  =  artist,  F  N  C  =  P  U  T  ,  R  E  Q  -  reqlst,  N  A  M  =fld,  NU  h  ■  idx,  'J  A  L  -  val,  L  E  N  -  ten 

Inputs  and  Outputs 


High-Level 

MACRO-11 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Inputs 


Requirement  or  Value 


arc; 


A  pointer  to  the  Argument  List. 
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FID 
FIDX 


FVAL 


RVM 
NAM 

NUM 

LEN 

VAL 


A  pointer  to  the  Required  Arfjiinients  List. 

A  field  name.  For  MACHO  11  only,  a 
pointer  to  a  (i-hvte  ASCII  Held  name. 

A  field  index  tor  the  specified  tield  (when  the 
field  is  indexed). 

(.An  input  value  for  MACHO  11  only)  the 
length  of  the  data  to  be  displayed  (must  he 
-1  for  ASCIZ  strinjis  and  0  tor  restoring  the 
default  field  value). 

The  field  value  to  he  displayed. 


Outputs 

None. 


None. 


Returned  Status  Values  and  Codes 


Status  Value 
High-Levei 
Languages 


1 

11 

-16 

-20 

21 


Status  Code 
(MACRO-in 


The  status  code  is  set.  For  MACHO   1 1  only, 
HO  points  to  the  Argument  List. 


Meaning 


FS.$SUC 
FK$FLD 

FK.$DLN 

none 

none 


Successful  completion 

Specified  tie'd  does  not  exist  (invalid  field  name  or 

index) 

Data  specified   for  output   too  long  (truncated  by 

Form  Driver) 

(For  high-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 


6.17    FPUTAL  —  Output  Values  to  All  Fields 

The  Form  Driver  outputs  the  specified  data  to  all  fields  in  the  form.  The  data 
for  each  field  must  match  the  length  '^f  that  field.  Data  must  be  arranged  in 
the  order  in  which  the  Form  Driver  would  retrieve  the  fields  if  an  FGETAL 
call  were  issued  for  the  form. 

If  the  data  that  you  supply  is  too  long,  the  Form  Driver  returns  an  error  to 
your  task  and  truncates  the  data.  If  the  data  is  too  short,  the  Form  Driver 
outputs  defaults  for  any  fields  for  which  no  data  is  provided. 

If  the  length  of  the  data  specified  is  zero,  the  P'orm  Driver  restores  default 
values  for  all  fields  in  the  form  and  clears  any  fields  that  do  not  have  defaults. 
(If  the  form  contains  any  scrolled  areas,  the  offset  to  the  current  line  for  each 
of  those  areas  is  re-initialized  to  zero,  with  the  top  line  as  the  current  line.) 
Thus,  the  FPUTAL  call  with  data  length  of  zero  is  one  way  to  re-initialize  a 
form.  It  is  the  only  form  of  the  call  that  is  valid  for  a  form  that  contains  a 
scrolled  area. 


Form  Driver  Calls    (5-21 


The  Form  Driver  does  not  valid; 
task.  This  is  true  tor  both  expli< 

ite  data  output  to  fields  from  the  application 

:-it  output  and  default  values.                                       ^^ 

FORTRAN  and  BASIC-PLUS-2  Ci 

all 

CALL   FPUTALf/ 

rah 

CALL  FPUTAL. 

COBOL  Call 

CALL    "FPUTAL 

"   USING  feci  I. 

CALL   "FPUTAL 

t 

MACRO-11  Call 

$  F  D  t.'          A R G  =  artist,  F  N C  -  P  A  L  .  P  E  0  - rcqlst. '.'  A L  ^^  val,  L  E  N    Icn                                                                      1 

Inputs  and  Outputs 

High-Level 

language 

Argument 

Abbreviation 

MACRO-11 

Keyword 

or 

Offset 

Requirement  or  Value 

Inputs 

— 

ARC 

A  pointer  to  the  Argument  List. 

— 

RKQ 

A  pointer  to  the  Required  Arjiunient  List. 

LK.\ 

(An   ini)ut   value  lor  MACMiO   11   only)   the 
lenfith  ol  the  data  to  he  displayed  (must  he                  ^^^ 
1  tor  ASCIZ  strings  and  0  tor  restoring  the                  ^^^ 
detault  field  values). 

FVAL 

VAL 

The  concatenated  field  value(s)  to  he  dis- 
played. 

Outputs 

- 

None. 

None. 

■['he  status  code  is  set.  For  MACRO   1 1  only, 
RO  points  to  the  Arfiument  List. 

Returned  Status 

Values  and  Codes                                                                                     ^^ 

Status  Value 

High-Level 

Status  Code 

Languages 

(MACRO!  n 

Meaning 

1 

Fs.s.src 

.Succe.s^lul  completion 

-12 

FK.SNOF 

No  lields  detined  for  current  form 

-16 

FK.SDLN 

l)ata   specified   lor  output    too   lonj;   (truncated    hy 
Form  Driscr) 

U> 

FE.SIFN 

Specified  call  invalid  in  current  context  of  form 

-20 

none 

(For  high-level  language  programs  only) 
Wrong  number  of  arguments  in  lail 

21 

none 

(For  high-level  language  programs  only) 
Impure  area  not  vet  initialized 

• 

()-22 

Form  Driver  Calls 

6.18    FPUTL  —  Output  to  Last  Line  of  Screen 

Tht'  Form  Driver  cltvars  the  last  line  ol  the  screen  and  displays  the  specified 
string  on  that  line.  On  the  VTlOO  terminal  with  the  advanced  video  option, 
the  Form  Driver  always  applies  the  bold  attribute  to  the  last  line  of  the  screen 
when  data  is  displayed  there  with  the  FPl'TL  call.  On  other  VTlOO  terminals, 
the  line  appears  underliiied  or  in  reverse  video  matching  the  cursor  that  the 
terminal  is  set  to  use.  (The  VTlOO  I'sor  duidc  describes  how  to  change  the 
VTlOO  cursor.) 

11  the  string  is  longer  than  the  current  maximum  line  length  for  the  terminal 
(80  or  V.V2.  characters),  the  Form  Driver  sets  the  status  code  as  shown  below 
and  truncates  the  string  when  displaying  it.  If  the  length  of  the  string  is  zero, 
the  Form  Driver  clears  the  last  line. 

This  call  is  the  only  means  by  which  your  task  can  access  the  last  line  of  the 
screen.  Otherwise,  the  last  line  is  reserved  lor  use  by  the  P'orm  Driver  to 
display  e,- —  messages  and  help  text. 

The  Form  uriver  does  not  examine  data  output  to  the  last  line  from  the 
application  task. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  F PUT Lffrnl) 

CALL   FPUTL 

COBOL  Call 

CALL   "FPUTL  "   USING  fval. 

CALL    "FPUTL"  . 

MACRO-11  Call 

$  F  D ','  ARC-  a  r^  Is  ^  F  N  C  --^  L  S  T  .  P  EQ  =  rrq  Is  / , '.'  A  L  :-  r  n  /,  L  E  N  -^  I  en 

Inputs  and  Outputs 


High-Levpl 

Lanituagp 

Argument 

Abbreviation 


MACRO  II 

Keyword 

or 

Offset 


Requirement  or  Value 


Inputs 


F\A1. 


AHC; 
HF.g 


VAI. 


A  pointer  to  the  Arfjument  List. 

A  pointer  to  the  Kecpiired  Arguments  List. 

(.An   input   vahie  tor  .M.ACHO   11   onlyl  the 
length  ot  the  data  to  he  displayed  (must  be 
1   tor  .ASCIZ  strinj;s  and  0  lor  clearing  ..le 
last  line  ol  the  screen). 

i'he  string  to  l)e  displayed  mi  the  last  line  ot 
the  screen. 


Ki)riii  [)iiver  ("alls     ()-2.'J 


Outputs 

NiiMf. 


Nunc 


Thf  -liitu-.  indf  i>  N(.|    K,ir  MACIU)    1  1  mily, 
Hti  pi'inl.-  In  the  Ar^iitiicnt  l,i-i. 


Returned  Status  Values  and  Codes 

Status  \aUn> 

MiKh-l.f\»>l  Status  Code 

l.ariKuaKrs  (MACRO   ID 


Meaning 


1 

Iti 

21 


Fsssrc 

KK>|)i.\ 

Il'iIlC 

null*' 


Niu  I  ('»tul  I  I'mplctinn 

hai.i   -ix'i  itit'd    tor  (luiput    ion   lnii^;   itruiuatt'd   1)\ 

Knrm  I  )riM'n 

I  For  hi^li  l»-\fl  langiianf  proutMri)-  onK) 

\Nriint;  iiuinher  nt  ar^iiiiienl-  iii  lall 

(For  hit:h  Ifvi'l  lan>;uaye  prn;;raiii>  onl\  i 

Inipiin-  area  rioi  yi-i  niitiali/ed 


6.19    FRETAL  —  Return  Values  for  All  Fields 

FHKTAL  rtMurns  a  concatenated  strinji  <>t  the  current  values  for  all  fields  in 
the  fortii.  The  order  of  the  tields  is  the  same  as  for  the  KdRTAL  call. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL   FRETAL   i ft  all 

COBOL  Call 

CALL    "FRFTAL"   USTNC  fml 

MACRO-11  Call 

$FDU  AFC    ,;ri.'/,s7.FNC  :-pAL  .FE0-n'(//,s7 

Inputs  and  Outputs 


HiKh-I  ovei 

l.anKUiiRe 

ArKumont 

Abbreviation 


MACRO   II 

Keyword 

or 

Offset 


Requirement  or  Value 


Inputs 


AK(; 


A  jiointfr  to  the  ArjiiiiiH'iit  I.i^t. 

A  pointer  to  till'  Kt'()iiir»'<l  Ar^imu-iits  Fist. 


Outputs 


Niiru' 


N'diu' 


FsLKNtHOi 


The  status  code  is  set.  For  MACHO   11 
only.  H<1  points  to  the  Argutiienl  List. 

The  ttttal  length  o|  all  fields  ui  the  iurin. 


F\AL 


K.SVAIjKO) 


The  cdiuateiiated  Nalucs  for  ail  tields  in 
the  Inrin.  F.-r  .MACHO  1  1  (.nly.  a 
IMtintcr  to  the  tdiicatenated  fields  mi  the 
uiipiire  area. 
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Returned  Status  Values  and  Codes 


Status  Value 

High-Level 

Status  Code 

Languages 

(MACRO!  1 

1 

FS$SIIC 

-12 

fe:$nof 

-20 

none 

-21 

none 

-22 

none 

Meaning 


Successlul  completion 

No  Fields  defined  for  current  form 

(For  high-level  language  programs  only) 

Wrong  numher  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 

(BASIC-PLUS-2   only)    Returned   string  is   longer 

than  the  declared  variable  length 


6.20    FRETN  —  Return  the  Value  for  the  Specified  Field 

The  most  common  use  for  this  call  is  to  get  the  value  of  a  particular  field  after 
a  call  to  get  all  fields  (FGETAL).  But  the  FRETN  call  may  be  issued  at  any 
time  after  the  Form  Driver  displays  the  form.  The  FRETN  call  always  returns 
the  current  contents  of  a  field. 

By  using  the  FGETAL  and  FRETN  calls  to  complement  each  other,  you  avoid 
having  your  task  deal  with  a  buffer  that  contains  all  the  operator's  responses 
for  the  form.  You  can  still  take  advantage  of  the  Form  Driver's  management 
of  all  terminal  interaction  and  use  the  FRETN  call  to  access  one  field  at  a 
time.  Other  calls  may  be  issued  between  FGETAL  and  FRETN. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FREJWfvai  fidifidx]) 

COBOL  Call 

CALL   "FRETN"   UEIHQ  fral.  fidifidx]. 

MACRO-11  Call 

$  F  D  U  A  R  G  =  artist.  F  N  C  =  R  T  N  ,  R  E  Q  =  re(/ /,s■^  N  A  M  =  fid.  N  U  ri  -  idx 

Inputs  and  Outputs 


High-Level 

MACRO-n 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Inputs 


FID 
FIDX 


ARG 
REQ 
NAM 

NUM 


Requirement  or  Value 


A  pointer  to  the  Argument  List. 

A  pointer  to  the  Required  Arguments  List. 

A    field    name.    For    MACRO-11    only,    a 
pointer  to  a  6-hyte  ASCII  field  name. 

A  field  index  for  the  specified  field  (when  the 
field  is  indexed). 


Form  Driver  Calls    6-25 


Outputs 


None. 


F\AL 


None. 
F.SLKNiRO) 
F.SV.AL(H(1) 


The  status  code  is  set.  For  MACRO-U  only, 
R()  points  to  the  Argument  List. 

The  length  oC  the  field. 


The  field  value,  including  padding. 


Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 

Status  Code 
(MACRO-ll) 

1 
-11 

FS$SUC 
FK$FLD 

-20 

none 

-21 

none 

-22 

none 

Meaning 


Successful  completion 

Specified  field  does  not  exist  (invalid  field  name  or 

index) 

(For  high-level  language  programs  only) 

Wrcmg  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 

(BASir-PLlIS-2  only)   Returned   string  is   longer 

than  the  declared  variable  length 


6.21    FSHOW  —  Display  a  Form 

The  Form  Driver  clears  only  the  portion  of  the  screen  required  for  the  speci- 
fied form  and,  starting  at  the  starting  line  number,  clears  the  screen  and 
displays  the  form.  When  first  displayed,  the  form  includes  all  text  and  the 
default  values  for  all  fields.  The  Form  Driver  clears  any  fields  for  which 
defaults  were  not  assigned  with  the  Form  Editor. 

If  a  starting  line  number  is  not  specified  in  the  call,  the  Form  Driver  uses  the 
starting  line  number  that  was  assigned  with  the  Form  Editor. 

If  the  starting  line  number  argument  is  specified  in  the  call,  the  Form  Driver 
starts  to  display  the  form  at  that  line.  If  the  form  description  specifies  the 
entire  screen  is  to  be  cleared  (lines  1  through  23)  the  Form  Driver  ignores  the 
line  number  specified  in  the  call. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  F SHOW fnaml line]) 

COBOL  Call 

CALL    "FSHOW"   US  lUG  fnamlJinr]. 

MACRO-11  Call 

$FDi,'  ARG  =  a/-,£,'/,sr,FNC-SHrJ  <REQ^reqlst,Hf\tA- form, \^U\A- line 
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Inputs  and  Outputs 

High-Level 

MACRO!  1 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Requirement  or  Value 


Inputs 


FNAME 


LINE 


ARG 
REQ 
NAM 

NUM 


Outputs 


None. 


None. 


A  pointer  to  Arfiunient  List. 

A  pointer  to  Required  Arjiunients  List. 

A  form  name.  For  MACRO- 11  only,  a 
pointer  to  a  (5-bvte  lorm  name. 

The  explicit  starting  line  number  for  the 
form,  overriding  the  line  number  assigned 
with  the  Form  Editor. 


The  status  code  is  set.  For  MACRO-11  only, 
RO  points  to  the  Argument  List. 


Returned  Status  Values  and  Codes 

Status  Value 

High-Level  Status  Code 

Languages  (MACRO-Il) 


Meaning 


1 

FS.$SUC 

6 

FE$ICH 

( 

FESFCH 

8 

FE$FRM 

9 

FE$FNM 

10 

FE$LIN 

18 

FE$IOR 

-20 


-21 


none 


none 


Successful  completion 

Invalid  channel  number  specified 

Form  library  not  open  on  specified  channel 

Invalid  form  definition 

Specified  form  does  not  exist 

Invalid  first  line  number  to  display  form 

Error  encountered  reading  form  library  (an  FCS  or 

RMS  system  error  code  that  provides  more  detail 

can  be  found  with  the  FSTAT  call  and  is  returned 

in  the  second  word  of  the  Status  Block) 

(For  high-level  language  programs  only) 

Wrong  number  of  arguments  in  call 

(For  high-level  language  programs  only) 

Impure  area  not  yet  initialized 


6.22    FSPOFF  —  Turn  Supervisor-Only  Mode  Off 

When  supervisor-only  mode  is  on  (the  def'auU  choice),  the  Form  Driver  treats 
fields  with  the  supervisor-only  attribute  as  display-only.  The  operator  may 
not  enter  data  in  such  fields.  Your  program  can  turn  supervisor-only  mode  off, 
making  fields  with  the  supervisor-only  attribute  accessible  to  the  operator,  by 
means  of  the  FSPOFF  call. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FSPOFF 
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COBOL  Call 

CALL   "FSPOFF"  . 

MACRO-11  Call 

$  F  D ','  A  rv  G  =  or^'/.s^  F  N  C  -  S  P  F  .  R  E  Q  =  reqist 

Inputs  and  Outputs 


High-Level 

MACRO-11 

Language 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Inputs 


Outputs 


None. 


ARC 
RKQ 


None. 


Requirement  or  Value 


A  pointer  to  the  Argument  List. 

A  pointer  to  the  Required  Arguments  List. 


The  status  code  is  set.  For  MACRO-11  only, 
R()  points  to  the  Argument  List. 


Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 


Status  Code 
(MACRO-11) 


Meaning 


I 
-20 

-21 


FS$SUC 
none 

none 


Successful  completion 
(For  high-level  language  programs  only) 
Wrong  number  of  arguments  in  call 
(For  high-level  language  programs  only) 
Impure  area  not  yet  initialized 


6.23    FSPON  —  Turn  Supervisor-Only  Mode  On 

This  call  turns  supervisor-only  mode  on  (the  original  or  default  condition). 
Fields  having  the  supervisor-only  attribute  are  handled  by  the  Form  Driver  as 
display-only;  the  terminal  operator  cannot  access  them. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FSPON 

COBOL  Call 

CALL    "FSPDN"  . 
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MACRO-11  Call 

$  F  D  U  A  R  G  =  ar,^lst.  F  N  C     S  P  N  .  R  E  Q  ^  rr;/ /.s7 

Inputs  and  Outputs 


High-Level 

MACRO-11 

I^anguage 

Keyword 

Argument 

or 

Abbreviation 

Offset 

Requirement  or  Value 


Inputs 


ARC. 
REQ 


A  pointer  to  the  Arf(ument  List. 

A  jjointer  to  the  Required  Ar{?uments  List. 


Outputs 


None. 


None. 


Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 


1 
20 

11 


Status  Code 
(MACRO-11) 


The  status  code  is  set.  For  MACRO- 11  only, 
RO  points  to  the  Argument  List. 


Meaning 


FSSSUC 
none 

none 


Suc'cesstui  eonipletion 
(For  hifjh-icvei  lanjjuage  programs  only) 
Wrong  number  ot  arguments  in  call 
(For  high-level  language  programs  only) 
Impure  area  not  yet  initialized 


6.24    FSTAT  —  Return  the  Status  from  the  Last  Call 

The  FSTAT  call  returns  the  status  from  the  last  call  to  the  Form  Driver.  The 
secondary  status.  STAT2,  has  an  FCS  or  RMS  error  code,  depending  on  the 
version  of  the  Form  Driver  that  you  are  using.  This  STAT2  value  is  useful 
only  when  the  value  of  STATUS  is  -4  or  -18.  indicating  a  problem  while 
opening  or  reading  a  form  library  file.  The  FCS  error  codes  are  documented  in 
the  lAS/RSX-ll  I/O  Operations  Manual.  The  RMS  error  codes  are  docu- 
mented in  the  RMS  11  I'ser's  (iuide. 

BASIC-PLUS-2  and  FORTRAN  Call 

CALL  FSJAJfstat[.stat2]) 

COBOL  Call 

CALL   "FSTAT"   USl\^\Q  statistat2]. 
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Inputs  and  Outputs 

High-Level 

Language 

Argument 

Abbreviation 


Inputs 
None. 


MA(RO-ll 

Keyword 

or 

Offset 


Requirement  or  Value 


Outputs 

STATUS 

SrAT2 
Returned  Status  Values  and  Codes 


Status  Value 
High-Level 
Languages 


Status  Code 
(MACRO!  I) 


A  numeric  code  tor  the  completion  status  ol 
the  last  Form  Driver  call  that  was  executed. 

A  numeric  RMS  or  FCS  status  code  tor  de- 
tailed information  when  the  STATl'S  value 
is    4  or     18. 


Meaning 


1 

20 

-21 


FS$Sl'C 
none 

none 


Successful  completion 
(For  hifth-level  lan^jua^je  profjrams  only 
Wrong  number  ot  arguments  in  call 
(For  high-level  language  programs  only 
Impure  area  not  yet  initialized 
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Chapter  7 

Form  Driver  Programming  Techniques  and 
Examples 


'I  his  c-hapttT  discusses  some  pro^Maniming  techniques  tor  u>iii^'  the  Form 
I)ri\er.  The  techiii()ues  discussed  iiulude  scrnHin^'.  simuhaiietms  (hsphix  <>t 
multiple  lorms.  u>iu^'  the  FdKTAL  call  with  F("iF/I'  and  Fl'F'I".  and  u>in^' 
indexed  field>.  Some  examjjles  ol  Form  Driver  pro^'ramnunt;  technitpie>  are  \u 
the  last  seition. 


7.1    Scrolling  Techniques 


A  si-rolled  area  is  defined  a>  a  number  ol  consecuti\e  unes  wuh  identical 
lormat.  The  purpose  ot  the  scrolled  area  is  to  allow  entry,  editing'  and  re- 
screen  at  one  time.  It  i>.  \n 


\  leuin^  ot  more  data  than  can  he  displayed  on 


the 


effect,  a  window  into  a  data  ha>e  which  is  manaiied  h\  your  callin^^  task.   The 
si/e  of  the  data  base  is  determined  h\  \(»ur  task,  and  it  is  not  limited  1)\  t  lie 


Form  l)ri\er 


impure  area. 


liuler  \our  task'>  direction,  the  Form  Driver  lontrols  the  strolled  area  t)\ 

>f  calls  to  ^et  data  and  to  process  field  terminator>.    The 


means  oi  a  series  • 


iirm  Driver  maintains  a  current  line  in  a  scrolled  area  and  re>triit>  \our 


ta-^k 


til  only  accessinji 


that 


line 


Thus  the  Form  Drivi'r  ii^nori's  ilie  index  \alue 


ar>rument  m  a  scrolled  area. 


When  a  form  is  displayed,  the  current  line  in  each  sirolled  area  i>  initialized 
to  the  top  line  of  the  scrolled  area.  The  lurrent  lines  identit>  is  updated  when 
field  terminators  are  processed  l)\  the  Form  Driver. 

To  pro\  ide  lomplete  support  tor  scrollini;.  your  ta.^k  mu>t  analw.e  the  field 
terminators  to  he  processed  and  update  the  screen  with  the  appropriate  data 
from  the  data  hase.  In  nvdvr  to  do  this,  the  task  must  maintain  ixiinters  into 
the  (lata  base  to  the  current  line  and  the  lurrent  window  of  the  scrolled  area. 
With  this  information,  your  task  can  exercise  complete  lontrol  o\er  the 
.scrolled  area  and  the  position  of  the  lurrent  line. 

When  lines  are  scrolled   forward,  the  task  must   provide  the  data  to  be  dis 
plaved  on  the  bottom  line  of  the  scrolled  area.  When  lines  are  scrolled  (jack- 
wards,  the  task  must  provide  the  data  to  be  displayed  on  the  top  line,  ihere- 


fore  \(iur  task  mus 


t  k 


now 


th( 


e  number  of  lines  in  the  scrolled  area  and  main- 


tain pointers  into  the  data  base  for  the  current  top  and  bottom  lines  ol  sour 
screen  as  the  data  is  scrolled  forward  and  backward. 

To  some  extent,  when  a  scrolled  area  is  |)hysically  sc''olled  it   is  under  the 
control  of  the  application  program.  Il  the  current  line  of  ;i  scrolled  area  is  the 


Ixittoiii  lint',  tlu'  KoMii  Driver  will  al\v;iys  scroll  the  area  when  (he  serol!  for- 
ward terminatcr  is  processed.  However,  il'the  current  line  is  not  the  bottom 
line,  tlie  area  is  only  scrolled  if  the  application  program  specifies  data  to 
update  the  bottom  line  in  the  Form  Driver  call  to  process  the  scroll  forward 
terminator  (FPP'I'l.  Otherwise,  the  cursor  moves  down  one  line  and  that  line 
becomes  the  new  current  line. 

The  same  applies  to  scroll  backward.  If  the  current  line  is  the  top  line,  scroll 
backward  always  causes  the  scrolled  area  to  scroll,  ll  the  current  line  is  any 
other  line,  the  arfi  scrolls  only  if  data  to  update  the  top  line  is  specified  in  the 
Form  Driver  call  to  process  the  scroll  backward  terminator.  Otherwise,  the 
cur.sor  moves  up  one  line  and  that  line  i)ecomes  the  new  current  line. 

The  Form  Driver  provides  calls  to  get  the  current  scrolled  line  (FINLN)  and  to 
output  data  to  the  current  scrolled  line  (FOl'TLN)  to  aid  you  in  imple- 
menting support  for  scrolled  areas.  If  you  wish  to  validate  the  fields  within  a 
scrolled  area  on  an  individual  basis,  you  may  wish  to  u.se  calls  to  get  a  speci- 
fied field  (FOKT)  in  combination  with  the  call  to  process  a  field  terminator 
(FFFT)  to  handle  input  in  a  scrolled  line. 

The  calls  to  get  all  fields  (FCIKTAL)  and  to  get  any  field  (FOKTAF)  are  illegal 
tor  a  form  that  contains  a  scrolled  area.  The  call  to  output  data  to  all  fields 
(FPl'TAL)  is  legal  for  a  form  with  a  scrolled  area  only  in  the  special  case  that 
restores  the  default  values  to  all  fields. 

When  you  define  forms  containing  scrolled  areas,  remember  that  the  Form 
Driver  does  not  maintain  te.xt  within  a  scrolled  area  (other  than  field-marker 
characters)  after  the  text  scrolls  off  the  screen. 

It.  however,  you  do  not  wish  to  support  all  the  features  of  .scrolling,  you  rnay 
choose  to  display  error  messages  instead  of  processing  certain  field  termina- 
tors. 


7.2    Three  Common  Scrolling  Methods 

The  three  common  methods  for  using  scrolled  areas  described  below  do  not 
exhaust  the  possibilities.  You  may  think  of  other  methods  more  suitable  for 
your  application. 


7.2.1    Entry,  Edit,  and  Review 

The  first  method  may  be  called  entry,  edit,  and  review.  This  method  uses  a 
scrolled  area  to  gather  many  lines  of  data,  each  one  of  which  contains  several 
fields.  The  operator's  interaction  with  the  form  in  this  case  is  similar  to  his  or 
her  interaction  with  an  FOKTAL  call.  The  scrolled  area  acts  as  a  window^  into 
a  .segment  of  the  data  being  collected.  The  operator  is  free  to  move  about  the 
form  arbitrarily  and  to  change  the  input  data.  When  tinished.  he  or  she 
presses  the  KNTER  key  to  signal  that  the  data  is  complete. 

To  use  this  method,  your  task  establishes  a  data  array  containing  enough 
space  for  the  maximum  number  of  scrolled  lines  that  you  want.  Employing 
the  calls  to  get  a  scrolled  line  (FINL.X)  and  process  a  field  (ermina(or  (FPFT), 
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the  task  exchan^^'s  control  with  the  Form  Driver  and  saves  the  data  line  l)y 
line  as  it  is  entered.  Whenever  the  Komi  Driver  passes  a  scrolling'  tield  termi- 
nator back  to  the  applii  ation.  the  task  must  take  appropriate  aetion  to  posi- 
tion itself  in  the  array. 

Your  task  can  control  which  line  ot  the  scrolled  area  the  Form  Driver  accepts 
data  on  by  choosing  whether  or  not  to  pass  data  to  be  displayed  on  the  top  or 
bottom  line  of  the  scrolled  area  with  the  call  to  process  a  field  terminator 
(FPFT).  If  no  data  is  passed,  the  Form  Driver  simply  moves  the  cvirsor  up  or 
down  one  line.  provi(led  the  cursor  is  not  on  the  first  or  last  line  of  the  scrolled 
area. 

I'he  boundary  of  the  available  data  space  may  be  reached  while  scrolling,  hi 
this  situation,  your  task  may.  without  processing  the  field  terminator,  print  a 
line  of  text  on  the  last  line  of  the  screen  nilbrmingthe  terminal  operator  of  the 
situation.  The  task  may  then  reissue  the  call  to  get  a  scrolled  line  (FINLN). 

You  may  wish  to  initialize  the  scrolled  area  to  some  values  other  than  the 
defaults  for  the  fields  that  it  contains.  'Iliis  can  be  done  by  issuing  calls  to 
output  a  scrolled  line  (FOl'TLN)  and  to  process  a  tield  terminator  (FPFT) 
along  with  the  scroll  forward  and  scroll  backward  terminators.  Each  line  is 
filled  by  the  FOUTLN  call,  followed  by  the  FPFT  call  scrolling  forward  with 
no  data  passed.  In  this  way.  each  line  is  lilled  in  turn.  Alter  the  last  line  is 
filled,  no  scroll  forward  is  done.  You  can  reposition  the  cursor  to  the  line  that 
you  want  by  issuing  several  FPFT  calls  with  scroll  backward  terminators. 

It.  on  the  other  hand,  you  wish  to  reinitialize  all  scrolled  area  lines  on  the 
screen  with  the  default  values  for  the  fields  that  they  contain,  you  can  use  a 
call  to  put  all  fields  (FPl'TAL)  that  passes  no  data.  The  entire  form  is  reini- 
tialized. 

A  form  may  have  more  than  (me  scrolled  area,  or  may  be  complex  because 
several  non-scrolled  fields  are  scattered  on  either  side  of  the  scrolled  areas.  In 
this  situation,  your  task  can  emulate  a  get-all  fields  operation  by  means  of  the 
tollovving  procedure:  the  task  uses  a  field  name  of  asterisk  (*)  to  get  the  first 
field.  Get -field  (F(iET)  and  process-field-terminator  (FPFT)  calls  are  then 
used  until  the  field  returned  from  the  FPFT  call  is  in  a  scrolled  area.  The 
method  of  scrolling  through  an  area  line  by  line  can  then  be  used  until  the 
terminator  received  is  one  of  the  exit  scrolled  area  terminators.  At  that  point, 
control  returns  to  the  previous  loop,  with  the  F^NTER  key  terminator  sig- 
nalling that  the  form  is  complete. 


7.2.2    Normal  and  Display-Only  Fields 

The  second  programming  method  for  scrolled  areas  employs  scrolled  lines 
containing  both  normal  and  display-only  fields.  In  this  method,  the  applica- 
tion task  uses  calls  to  get  a  ,Ad  (F(IET)  to  accept  data  from  the  operator. 
The  task  then  validates  fields  individually.  Using  data  that  the  operator  en- 
tered, the  task  also  computes,  or  finds  in  a  data  base,  new  values  for  display- 
only  fields.  These  new  values  are  then  output  to  the  form  by  means  of  the  call 
to  put  a  field  (FPUT). 
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Under  the  second  method,  the  task  must  build  scrolled  lines  I'rom  the  indi- 
vidual fields  so  that  the  call  to  process  a  field  terminator  (FPi-T)  can  be  used 
and  so  that  data  can  be  output  to  the  top  and  bottom  lines  of  the  area  when 
scrolling  takes  place.  The  algorithm  employed  for  scrolling  itself  is  essentially 
the  same  as  in  the  first  method  described  above. 

7.2.3    Reviewing  a  Data  List 

A  third  method  of  scrolling  is  useful  for  reviewing  a  list  of  data,  hi  this 
n:eth()d.  a  task  provides  access  to  a  long  list  of  data  or  other  information  and 
allows  the  operator  to  review  the  data  or  read  the  information.  It  is  not 
possible,  however,  to  get  a  scrolled  line  (FINLN)  in  a  scrolled  area  whose 
fields  are  all  display-only.  To  circumvent  this  difficulty,  you  can  use  a  single 
character  field  with  the  no-echo  attribute  to  obtain  a  field  terminator,  thus 
allowing  the  task  to  scroll  lines  of  data.  The  cursor  appears  on  the  line  in  the 
no-echo  field  to  mark  the  point  of  interest  for  the  operator. 

7.3    Simultaneous  Display  of  Multiple  Forms 

You  can,  if  you  wish,  display  more  than  one  form  at  the  same  time.  If  you 
specify  a  line  number  other  than  zero  as  the  beginning  of  a  form  and  use 
P\SHOW  rather  than  FCLRSH,  the  Form  Driver  offsets  the  form  dynamically 
at  run-time  to  overlay  the  form  that  is  currently  displayed.  Keep  in  mind, 
however,  that  unless  you  pr  /v-ide  a  separate  impure  area  for  each  form  on  the 
screen,  the  P\)rm  Driver  knows  about  only  the  last  form  displayed,  and  your 
task  can  reference  only  that  form. 

In  designing  an  application  which  is  to  display  multiple  forms  simultaneously, 
it  is  important  to  define  the  help  forms  correctly.  When  the  Form  Driver 
restores  the  screen  after  a  help  form  has  been  displayed,  only  the  form  for 
which  the  Form  Driver  currently  has  the  impure  area  pointer  can  be  restored. 
If  for  example,  two  forms  were  displayed  and  the  help  form  cleared  the  entire 
screen,  only  one  form  would  be  restored.  To  avoid  this,  each  help  form  should 
only  clear  the  area  of  the  screen  cleared  by  the  form  it  is  associated  with  (as 
defined  by  the  first  and  last  line  numbers). 

The  screen  refresh  function  ^KB  redisplays  only  the  current  form.  Any  help 
or  other  forms  that  are  also  on  the  screen  are  not  refreshed  and  are  therefore 
erased  from  the  screen. 


7.3.1    Impure  Areas 

Separate  impure  areas  are  required  only  if  several  forms  are  to  be  accessed 
interchangeably  by  calls  to  the  Form  Driver  to  get  or  put  fields.  It  your 
application  program  is  going  to  display  one  form,  complete  the  processing  for 
it,  and  then  display  the  next  form  without  erasing  the  first.  Onh'  one  impure 
area  is  required  as  long  as  your  application  makes  no  attempt  to  access  the 
first  form  again.  In  this  manner,  any  number  of  forms  can  be  displayed  simul- 
taneously using  only  erne  impure  area. 
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When  you  use  more  than  one  impure  area  to  display  multiple  forms  simulta- 
neously, eontrol  may  be  switched  Ireely  between  the  two  lorms  by  the  task. 
The  forms  themselves  and  any  help  forms  that  they  call  upon  must  be  defined 
with  line  numbers  that  do  not  interfere  with  each  other. 


# 


7.3.2    Help  Forms 

Displayinfi  multiple  forms  simultaneously  is  particularly  useful  tor  helj) 
forms.  It  is  possible  to  define  help  forms  so  that  when  displayed  they  leave  the 
current  form  intact  on  the  screen.  Only  the  portion  of  the  screen  that  is 
specified  in  the  help  form  definition  is  cleared.  Thus,  if  the  help  form  is 
defined  to  be  displayed  between  lines  If)  and  2.'5,  the  Form  Driver  clears  only 
that  portion  of  the  screen.  The  original  form  occupies  the  remainder  of  the 
screen. 

Note,  however,  that  if  the  Form  Driver  displayed  the  initial  form  with  a  line 
offset  it  will  use  the  same  number  to  offset  the  heli)  form.  If  the  help  form  does 
not  fit  on  the  screen  after  the  offset  is  applied,  the  P'orm  Driver  returns  an 
error  to  your  task. 

If  you  define  a  help  form  or  any  other  form  in  its  form  description  as  being 
displayed  between  lines  1  and  2.S,  the  Form  Driver  clears  the  entire  screen 
and,  ignoring  the  starting  line  number  in  a  call,  displays  the  form  as  defined. 

When  a  help  form  and  a  current  form  are  displayed  simultaneously,  the  Form 
Driver  completely  redisplays  the  current  form  when  the  terminal  operator 
signals  that  he  or  she  is  finished  with  the  help  form.  All  or  any  part  of  the  helj) 
form  that  does  not  overlap  the  current  form  remains  on  the  screen. 


7.4    Emulating  the  FGETAL  Call  by  Combining  the  FGET  and 
FPFT  Calls 

The  principal  advantage  of  the  call  to  get  all  fields  in  a  form  (F(IETAL)  is 
that  the  F^orm  Driver  takes  charge  of  all  input  at  the  terminal.  An  FCiFn'AL 
call  returns  to  vour  task  only  when  the  terminal  operator  signals  completion 
by  pressing  the  ENTB:R  or"  RETURN  key.  The  disadvantage  of  FCiETAL, 
however,  is  that  your  task  cannot  respond  to  and  edit  input  on  a  field  basis  as 
it  is  entered  by  the  operator. 

You  can,  however,  emulate  an  FGETAL  call  with  a  combination  of  the  get- 
field  (FGET)  and  process-field-terminator  (FPFT)  calls.  A  similar  emulation 
can  be  done  with  the  get-any-field  (FGETAF)  and  FFPT  calls.  See  the  ex- 
ample in  Section  7.2.1. 

The  call  to  return  all  fields  (FRETAL)  may  be  used  to  obtain  the  entire  record 
for  processing  after  the  form  has  been  entered  by  the  terminal  operator. 


7.5    Using  the  FGETAF  Call 


If  a  form  contains  a  number  of  fields  any  one  of  which  would  be  sufficient 
input  for  the  form,  the  call  to  get  any  field  (FGETAF)  is  particularly  useful. 
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For  example,  a  form  may  contain  fields  for  an  account  number  and  a  name. 
^'our  task  needs  one  of  these  to  locate  a  customer's  record  in  a  data  base.  The 
call  to  get  any  field  allows  the  terminal  operator  to  enter  data  in  either  of  the 
two  fields.  The  operator  can  choo.se  the  one  for  which  information  is  available. 
The  P'orm  Driver  returns  only  the  data  for  the  chosen  field  to  the  task. 

In  a  form  that  contains  a  menu  from  which  the  operator  is  to  select  one  item, 
KCIKTAF  may  be  used  to  allow  him  or  her  to  position  the  cursor  in  the  chosen 
field  and  press  the  ENTF:R  key. 


7.6    Using  Indexed  Fields 


Identical  fields  on  consecutive  lines  of  a  form  may  be  defined  as  indexed. 
Indexed  fields  make  it  possible  to  design  smaller  forms  with  smaller  impure 
area  requirements.  If  a  Ibrm  has  many  fields,  indexing  can  be  an  important 
advantage. 

Your  task  can  reference  any  field  in  a  form,  whether  indexed  or  not  indexed, 
by  specifying  the  field  name  and  index  value  (the  index  is  an  integer  from  1  to 
N  where  N  is  the  repeat  count  for  the  field).  If  tiie  field  is  not  indexed,  the 
Form  Driver  ignores  the  index  value. 

The  order  in  which  the  Form  Driver  moves  through  indexed  fields  depends  on 
whether  the  fields  are  defined  as  a  vertical  or  horizontal  array.  If  the  array  is 
defined  as  vertical,  the  Form  Driver  moves  down  the  form  through  each  ele- 
ment of  the  array  before  mcn'ing  to  the  field  after  the  first  element. 

You  can  define  multiple  fields  as  a  horizontal  array,  if: 

1.  the  first  occurrence  of  each  field  is  on  the  same  line  of  the  form 

2.  the  repeat  count  is  the  same  for  all  fields 

■\.    there  are  no  intervening  fields  on  the  first  line  of  the  array. 

Fields  defined  as  horizontal  arrays  that  do  not  meet  all  these  requirements 
default  to  vertical  arrays. 

In  a  horizontal  array,  the  F'orm  Driver  moves  across  each  line  of  the  array, 
through  each  field,  before  going  on  to  the  next  line.  Thus,  horizontally  in- 
dexed fields  allow  grouping  of  related  fields  together,  not  only  in  the  order  in 
which  data  is  entered  on  the  screen  but  also  in  the  order  of  the  data  returned 
by  a  call  to  get  all  fields  (FGETAL). 


7.7    Examples  of  Programming  Techniques 

This  section  contains  several  code  segments  written  in  FORTRAN  IV.  The 
techniques  for  programming  are  the  same  for  all  languages.  If  you  are  familiar 
with  MACRO-11,  the  last  part  of  this  secticm  is  a  series  of  MACRO-11  pro- 
gram examples. 
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7.7.1    Emulating  FGETAL  with  FGET  and  FPFT 

The  FdET  and  FFFT  calls  may  be  used  to  emulate  a  call  to  get  all  fields  yet 
still  allow  the  calling  program  to  validate  responses  immediately  on  entry, 
before  proceeding  to  the  next  field  in  the  form. 


CALL  FCLrvSH  (FORM) 

CALL  FGET  TvESP.  TERM.  "*") 

CALL  FGCF  (FIELD) 

GOTO  2 


1 1  e  c  e  5  s  a  r  V 
CALL  FGET  (RESP-  TERM.  FIELD)   '  Get  a  field 


'  D  1  5  p  1  a  •/  t  h  p  form 

'  Get  first  field  i  I'l  form 

I  Gel  the  ri  a  m  e  of  the  field 

'  '.'  a  1  1  'J  a  t  e  response  if 
I 
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'.'  a  1  1  d  a  t  e  the  1 1  s  e  r  '  s  r  e  s  p  o  ri  s  e  . 

F  0  1  1  0  IaI  1  i"i  iJ  u  a  1  1  'J  a  t  1  0  ri  .  the  "  a  r  i  a  !■  1  e  "  E  R  R  •.'  A  L   is  r  e  r  o 

if  the  r  e  s  p  0  ri  5  e  is  i '  a  1  i  >  J  •  vi  o  ii  -  z  e  r  o  if  i  1 1  "  a  1  i  'd  . 


F  '  ERR'.'AL  .^t  .  0  '     I'^T'^  ' 
F  'TERM  .F'J.  (V)  GOTO  \0 

CALL  FPFT 

CALL  FGCF  (FIELD) 

GOTO  1 

CALL  FRETAL  (DATA) 


Get  field  again  o  ri  error 

Branch  if  t  p  r  m  i  n  a  t  o  r  i.i  a  s 

"ENTER 

Else  proce':  s  fielil  tprmiriator 

Get  1 1  a  III  e  of  field  to  get 

Get  I'l  e  H  t  field 

Return  r  p  s  p  0  ii  s  e  s  for  all 
fields 


7.7.2  Table  Lookup 

(let  the  response  for  a  field  and  validate  it  against  a  table  of  valid  responses. 
The  list  of  valid  responses  is  contained  in  the  form  as  named  data  (the  data 
name  is  the  same  as  the  field  name). 

As  an  example,  consider  the  field  'MONTH"  defined  as  picture  AAA.  The 
corresponding  named  data  'MONTH'  contains  the  table  of  valid  responses  for 
the  field  in  the  form. 

Note  that  the  named  data  is  returned  as  an  ASCII  string  terminated  with  a 
null. 

CALL  FGET  ''.'ALUE.  TERM.  FIELD*  '  Get  the  fipld 

..ALL  FLEN  'LENGTH.  FIELD*         i  Get  the  field  length 

CALL  FNDATA  'FIELD.  '.'ALID'        i  Get  c  o  r  r  e  s  p  o  n  d  i  n  g  named  data 

PTR  =  1  '  I  n  1  f  1  a  1  1 r  e  I  nde  K 

DO  3  I  =  1  .LENGTH  •  Check  for  "alid  responsp 

IF  (  i.'AL  ID'  PTR+ I  1'  .FO.  o  '  GOTO  5     '  Error  if  not 
IF  O.iALID'  PTR^-I  ■  1  ■  .NE.  '.'ALUE*  I))  GOTO  U 
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CONTINUE 

com  6 

PTTv  -  PTR  +  LENGTH 
GOTO  2 

TALL  F  P  U  T  L  '  "  I  1  1  e  9  a  1  r  e  =  p  o  .  ^  t-  t 
GOTO  1 


U  F  .j  a  t  e  1  1 1  '1  p 


field"  ' 
'  II  e  ?  s  a  y  e 
'  Get  f  1  o  1  .1  5  3  n  1  .. 


L'  I  -  F  I  J   e  r  r  n  r 


7.7.3    Form  Linkage 

Naiiu'd  data  iiia\   he  ust-d  to  proxidi'  auiDinatii-  lonii  linkage  independent  o 
the  a|)pli(ali(>n  pm^'rani. 


CALL  FCLrvBH  •  "FirvST  "  < 

CALL  FGET  'PESP.  TERM.  " ♦ "  > 

CALL  FGCF  'FIELD! 

GOTO  3 


'  D  1  =  F  1  a   f  0  r  i?i 

'  G  e '  f  1  r  ?  »  field  if'  fori" 

'  G  e  f  the  ci  a  m  t^  of  t  h  ?  f  i  p  I  d 

'  P  r  0  c  e  ^  =  r «?  <=  P  0  11  ■;  p 


CALL  FGET  'RESF.  TErvM.  FIELD'  '     Get  -i  f  i  «^  1  d 


Process  resForise 


IF  ■■  EPCv'.'AL  .NE  .  ''  '  GOTO  2 
IF  '  TERM  .EO.  0  '  GOTO  4 
CALL  FPFT 
CALL  FGCF  'FIELD) 

GOTO  : 

IF  (FNDATA  <"N'TFrvM".  FORM 

CALL  FCLR5H  ■FORM* 

STOP 


'  Get  f  1  p  1  ij  a  9  a  1 1'l  o  ii  error 

'  Branch  if  t  e  r  w  i  ii  a  t  o  r  "ENTER 

'  E  1  ?  e  process  field  t  e  r  ni  i  i  >  a  t  n  r 

'  Get  1 1  a  If  e  of  field  to  3  e  t 

'  Get  I  ■  e  M  t  f  1  e  1  il 

L  T  .     0  '     GOTO    5     I     Get     riame     of 

'  1 1  e  V  I     form 

'  D 1  ?  F  1  a        It      if     there     i  -;     one 

'  Else     e • I ♦ 


7.7.4    Menus  and  Application  Data 

.Named  ciata  can  be  used  tn  facilitate  dexeli'prneni  ot  menu  dri\en  applica- 
tions ami  to  store  torm  specific  information. 

.As  an  example  consider  the  menu  form  named  FIKST,  Figure  H  1.  The 
named  data  c<-ntains  the  name  of  the  appropriate  form  to  display  for  each  of 
the  po.s.sihle  functions  and  the  name  of  the  corresponding  file  to  be  written. 

ChLL  FCLRSH  I  "MENU"  I  '  Disrla   meo-i  form 

CALL  FGET  'RESP.  TERM.  "FIELD"-   '  Get  r e ? f o n t e 


IF  .FNDATA  iRESP.  FORM 


T  .     '■>  '     GOTO    r     '     Get     r  o  r  r  e  -  f  o  r.  d  i  r.  9 
'     'I  a iti  e  d    d  a  t  a 


CALL    FPUTL     •  "Illegal     choice"'      '      If     none.     ni"alid     resFonse 
GO  T  0     1  I     G  p  t     t  h  e     f  1  f-  1  d     a  9  a  I  1 1 
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CAIl      rnNTAT      (PESF''.     "T".     PMAM  ■      '     f,pt      i,-,,,,*-!     .lit.,     naiiif     for     filP 
CAi.l      rrJDATA     a)NAM  .     I    lif'  t     r,ct     mh.x'     n  f     <  n  r  r  f-.  p  <. ..  .1  i  ,.  ( 

I      til  I. 


CAIl    r  (  ,  r.",n    '  f  iir.'M 


D  t  >:  r  I  ,1  f  r.  I  III      r-i  ,i,\      p  f  n  I    pi;  s 


7.7.5    Initializing  a  Scrolled  Area 

This  example  illustrates  how  to  initialize  a  5  line  scrolled  area  in  a  form. 


CALL     FCLfvSH     '  "FORM' 


'       D  1  %  P  1  'T  •■       f  (J  I 


C  I  11  1  t  1  a  1  1  r  e  the  f  i  r  i.  t  line  in  t  h  e  '-.  r  rolled  av  p  , 


CALL  FOUTLN  i  "FIELD"  .  A'  1  •  1 


N  0 1.'  scroll  for  m  a  r  d  a  ri  d  1 1  >  i  t  i  a  1  i 


I  v.  1  t  1  0  I  1  r  ►•  *  1  I   • 


t  h 


u  P  >  t      line  II  r 


t  1  1   t  h  c- 


C  s  c  r  e  e  ii  i  '■;  i  1 1  i  t  i  a  1  i  r  e  d 


DO  1  I 


TO 


TALL  FPF''  '  8  .  "F  IE  ID 
CALL  FOUTL  N  ■  "F  I  ELD" 
CONTINUE 


A  (  1  .  I 


I  11  I  t  1  a  1 


f  0  r  I.I  a  r  d     t  o     n  e  /  t      |  i 
e     I  1  11  e 


C     N  0  I.I    III  0  "  e     b  a  c  I     to     the     f  i  r  -  t      ]  i  ri  e     of     the     5  c  r  o  1  1  e  d     are  a     t  o 

C      5  0  1  1  C  1  t      1  II  P  u  t    . 


DO 


I     -     1     TO    4 


CALL  FPFT  f  9  .  "F lELD"  ) 


CONTINUE 


I  S  c  r  0  1  1  b  a  c  f  i.i  a  r  d  t  n  p  r  e  "  i  o  i 
I   I  1  n  e 


7.7.6    MACRO-11  Programming  Examples 

This  section  contains  MACRO-11  examples.  Each  of  the  following  examples 
assumes  that  the  initialization  code  precedes  it. 


,  MCALI.   $FDU  .$FDUDF  .*EK  I  T 
tFD'JDF 


i  DEFINE  ARGUMENT  LIST  SIZES 
;  'FtASIZ  AND  FtRSIZ) 


ISIZ 
ARGLST  : 


.  B  L  KB    F  $  A  S  I : 


;  IMPURE  AREA  SIZE  IN  B.TE5 
;  ALLOCATE  SPACE  FOR  ARGUMENT 
!  LIST 
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REQLST: 
IMPUPE : 

STAT  : 


.r^LKB 

F$PSIZ 

.  worvD 

I  S  I  Z 

.  P  L  K  B 
.  P  L  K  W 

ISIZ-2 

ALLOCATE  SPACE  FOP  REQUirvED 

ARG  LIST 

SIZE  OF  IMPURE  AREA  IN  BYTES 

IN  FIRST  WORD 

THE  IMPURE  AREA 

2  Wn  RD  STATUS  BLOCK  REQUIRED 


I  I'l  1  t  1  -J  1  ;  ;:  e  t  h  p  r  e  q  M  1  r  e  iJ  a  r  3  i.i  in  e  n  t  s  lis  t 
MO  I.' 


MO'.' 
M  n  I.I 
M  n ',' 
•tFDU 


»PEgL5T  ,R0 

»STAT  .F$STS( RO  ' 

»1  .F*CHN(RO  ' 

«*  IMPURE  .F*  IMP  '  PO 


REQUIRED  ARGUMENTS  LIST 

POINTER 

STATUS  ELOCI-  POINTER 

L  I  B  P  A  R  1  L  H  A  N  N  E  L  N  U  M  B  E  R 

IMPURE  AREA  POINTER 

LIST 


Api-ri»ARGL3T  .REO-ttREOLST      :     INIT     PEO    AP 

;     POINTER 


In  each  of  the  following  examples,  the  argument  list  pointer  is  specified  in  the 
first  call  to  the  F'orm  Driver  only.  The  pointer  does  not  have  to  be  specified  in 
succeeding  calls  unless  RO  (which  contains  the  argument  list  pointer)  is  modi- 
fied. 

The  following  examples  also  assume  a  debugged  application.  In  s'ich  an  appli- 
cation, no  errors  returned  from  ihe  Form  Driver  are  possible,  except  for  I/O 
errors  resulting  from  reading  forms.  P'or  this  reason,  the  examples  below  check 
for  errors  only  on  return  from  calls  to  display  forms  or  to  solicit  input  from  the 
terminal  operator.  An  I/O  error  can  result  if  the  terminal  operator  requests  a 
help  form  or  screen  refresh. 


7.7.6.1  Example  1:  FGET/FPFT  in  Place  of  FGETAL  —  This  example  emulates 
a  call  to  get  all  fields  by  using  successive  calls  to  get  a  specified  field  and 
process  a  field  terminator. 


PI  ELD  I:  .ASCII 


FORM 


/  *  / 


ASCII   /FORM 


FIRST  CHARACTER  OF  FIELD 
NAME  ■*' 

TO  GET  FIRST  FIELD  IN  FORM 
FORM  NAME 


1  Ct  $ 


$FD'.i 

BCS 

$FD'.i 


APG  =  «ARGLST  .  PNC  - CSH  .  N AM  - «FORM  .  NUM  »0  ;  DISPLAY 

;  FORM 
ERROR  ;  BP  IF  t.O  ERROR 


NAM-ttFIELDl 


■'  Get  a  s  p  e  c  1  f  1  e  iJ  field 


;  INITIALIZE  ARGUMENT  L^IST  FOR 

;  FIRST 

;  FIELD  TO  GET 
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20$ 


*FDU 

FNC=GET 

DCS 

ERrvOR 

MO  I.I 

F$NAM(  RO  ■' 

.Rl 

CALL 

PRS^LD 

BCC 


I  1"!  1 '  a  1  1  d     1  ri  p  Li  t 
$  F  D  I.' 


301' 


PR 


GET     THE     SF'EriFlED     FIELD 

PR     [f       [     D    ERROR 

GET  POINTER  TO  FIELD  NAME 

FALL  ROUTINE  10  PROCESS 

f  i\  \   0 

UN  RF  TORN  r  CLR  [F  VALID 

IN  POT 

ELSE  R1  POINTS  TO  ASCIZ 

ERROR  MFSSAGE 


FNCn.5T  -OAI.  R  1  0  EN  **  ■■  1 

;  OUTPUT  ERROR  MESSAGE  TO 

;  LAST  LINE 
ZOf  ;  GET  SAME  FIELD  AGAIN 


'.'  a  1  1  d  1  1"!  p  u  t 


Si'i* 


*FDO 
CMP 
PNE 
CMP 


F  N  C  ^  T  R  M 

«FT$NTR  .F$TRM( RO 

2  0$ 

«FS$ItsC  .STAT 


PEO      20$ 

i    D  0  i-i  p    M  1  t  h    f  0  r  III  •     r  e  "  1  ri  1  t  1  a  1  1  z  e    to     get     a  g  a  i  v 
aO$:  $FDO  FNC-PAL  .LEN---«':' 

D  R        1  0  $ 


PROCESS  FIEI  D  TERMINATOR 

FIELD  T  E  R  M  I  N  A  T  0  R  -  E  N  T  F  R  •? 

PR  IF  NOT 

ELSE  CHECK  FOR  INfOMPLFTE 

FORM 

GET  FIELD  IF  FORM  INCOMPLETE 


RESTORE  DEFAULT  VALUES  TO 

ALL  FIELDS 

GET  FORM  AGAIN 


E  R  R  M  S  G  :   ,  A  S  C  I  2   ♦ratal  I  ■'  0  Error* 

.EVEN 
ERROR:   $FDO  FNC^^LST.  0  AL  -  »ERRMSG  .  LEN  =  **-1 

$E-.  IT 


7.7.6.2    Example  2:  Named  Data  —   This  example  illustrates  a  possible  use  of 
the  named  data  feature. 


MENU: 


.ASCI  I 


MENU     . 
/ERROR 


SELERR:      .ASCII 
;     ERROR    MESSAGE 
ERRLEN     =  ,-ERRMSG 

.  EVEN 


;     FORM    NAME 
SELECT    ANOTHER    FORM/ 


D  1  =.  p  1  a  V    fii  e  I'l  u     for  in  a    f  o  r  (n    m  i  t  h     a     list     of    f  u  n  c  t  i  o  vi  s    i-i  i  t  h    a 

vi  ij  III  ti  e  r     from    1-5    associated    i*i  1 1  h    each.     The    form    c  o  n  t  a  i  n  <;    o  n  I  v 
one    field     -     a     1  -  b  v  t  e    numeric    field.     Therefore     t  he    ■!  a  t  a     r  e  t  ij,  r  n  e  d 
from    a    call     to     d  e  t     all     fields     is     9  li  a  r  a  n  t  e  e  d    t  o     be    a     1  •  b  v  t  e 
'    ASCII     d  1  9  1 1     from    0  ••  9  . 
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10$ 


$FDU  ARG-- wARGL  ST  .FNT    C5H  .NAM     ttMENIJ.UUM    »n     "i     DISPLAY    FORM 

BCS  ERROR  ;     h3R     IF      in    FRRHR 


;  GEil     Hi  I      riFlJJS 

!  BR     IF     I  '0    ERROR 

!  GET     1     BYTE     RESPONSE 

;  CONCERT    DECIMAL     TO    BTNARY     tJALUE 


$FD'.' 

FNC^  ALL 

BCS 

ERROR 

MOUB 

@F$i.'AL  (  RO  > 

.R1 

SUB. 

4  '  ( )  ,  R  1 

i     Get.     |-|  a  (II  p  ij     ij  a  t  a     b'  •      1 1  i.i  m  L'  e  r      '  m  '=  i  n  9     ii  m  m  t'  e  r     e  i"i  t  e  r  e  ■!     i 


I  I     III  f  I 


I.I     f  0  r  m  ' 


$FDi.'     FNC  -■■  DAT  .NAM-^«n  -NL.IM  '  Rt 
;  GET  NAMED  DATA 


BCC 


:o$ 


IF  C-CLR.  NAMED  DATA  FOUND 
ELSE  IN'JALID  NUMBER  'INUALID 
INPUT  » 


LINE 


I  n  II  a  1  1  id  1  ri  p  i.i  t  i  n  m  e  n  >>     f  o  r  m 

$FD',»  FNC^LST  .i.'AL  =  «SELERR  .LEN-ttEPPLEN  :  OUTPUT  MESSAGE  TO  LAST 

BR  10$  ;  GET  FIELD  AGAIN 

'.'  a  1  1  d  1  )-i  p  u  t  -  d  1  <5  p  I  a  .  r  e  =1 1 1  e  ?  t.  e  ij  f  c  r  m 


!0t:      *FD'.'     FNC^CSH  .NAM- F$'.'AL  (  Pii  '  .NUM-«0  !  DISPLAY  FORM 
BCS      ERROR  ;  BR  IF  I/O  ERROR 


ERRMSG:  .ASCIZ   ♦Fatal  I/O  Error* 

EUEN 

ERROR:   $FD'.i  FNC-LST.  U  Al  -  «EPRMSG  .  LEN^^»^-1 
$E)',  IT 


7.7.6.3    Example  3:  Combining  the  FGETAL  and  FRETN  Calls  —   This  example 
illustrates  use  of  the  get-all-fields  and  return-field  calls. 


FORM: 
FLOLST 


ENDLST  = 


ASCI  I 

ASCI  I 
WORD 
ASCI  I 
WORD 
ASCI  I 
WORD 
ASCI  I 
WORD 


*FDU 

BCS 

$FD'.' 

BCS 

MOO 


/FORMOl 

/FIELDl . 

PRSFl 

'FIELD2 

PRSFZ 

/FIELDS 

PRSF3 

/FIELDS 

PRSFa 


;  FORM  NAME 

;  LIST  OF  FIE L  D  N  AMES 
;  AND  ROUTINE  TO  PROCES' 


EACH  FIELD 


APG  =  «ARGLST  .FNC=  CSH  .NAM  ^wFOPM  .NUM  # 

FORM 
EFRGR 
FNC  =- ALL 
ERROR 
wFLDLST  .Rl 


DISPLAY 


BR  IF  I /O  ERROR 

GET  ALL  FIELDS 

BR  IF  I/O  ERROR 

GET  POINTER  TO  FIELD  LIST 
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1  0  *  : 


$FDU 

FNC  PTN  .NAM  R 1 

ADO 

«  G  .  R  1 

CALL 

(a  (  p  1  If 

CMP 

Rl  .»ENDLST 

BL  0 

t'"i$ 

GET  Rt- -PONSE  FOR  FIELD 

SKIF'  OUER  FIELD  NAME 

CALL  ROUTINE  TO  PROCESS  FIELD 

ALL  FIELDS  DONE'? 

REPEAT  IF  NOT 


ERRMSG:   .A5CIZ   *Fatal   10  Error* 
E'.'EN 

error:  $fd'.'  fnc.-.lst-  u  al  -  »errmsg  .  l  en  tt  -  1 
i;e;;it 


7.7.6.4  Example  4:  Using  FGET  to  Synchronize  with  Terminal  Operator  —  Fhis 
example  shows  use  ol'  a  "special  get"  call  to  synchronize  the  task  with  the 
terminal  operator. 


FQRMl 
FORM  2 
FIELD 


ASCII  FORMiM/ 
ASCII  /F0RMO2/ 
ASCII    FLDNAM/ 


FORM  1 
FORM  2 
NAME  OF  DISPLAY-QNL' 


F  I  E  L  D 


tFD'.'     ARG  =  «ARGLST  .FNC  =  CSH  .NAM=«F0RM1  .NUM-ttO  ;  DISPLA' 

;  FIRST  FORM 
BCS      ERROR  ;  BR  IF  10  ERROR 

$FDi.'     FNC  =  ALL  !  GET  ALL  FIELDS 

BCS      ERROR  ;  BR  IF  10  ERROR 


.  P  r  0  c  e  5  s  data  (  3  e  t  p  n  i  ri  t  8  r  t  o  data  t  o  o  <>  t  p  i  ,i  t  i  n  R  1 
I e  n  3  t  h  in  R  2  ) 


FIELD 


$FDU     FNC  =  PUT  .NAM-»FIELD  »'v'AL-Rl  .LEN-R2  !  OUTPUT  TO  DISPLAY  ONLY 


$FD'.' 

BCS 
*  F  D  I.' 
BCS 


F  N  C  =  G  E  T  .  t-J  A  M  =  «  0 


ERROR 


DO  GET  WITH  NO  FIELD  SPECIFIED  TO 
WAIT  FOR  USER  ACKNOWLEDGMENT 
BR  IF  I  /O  ERROR 


FNC  =  CSH  .NAM^»FORMZ  ?  DISPLAY  NE;:T  FORM 
ERROR  ;  LR  IF  I/O  ERROR 


ERRMSG:  .ASCIZ   *Fatal  I/O  Error* 
.EUEN 

error:  $fdu  fnc^lst.  ual  =■  »errm5g  .  len-»1 
$e:;(It 
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Chapter  8 

Preparing  Your  System  for  FMS-H  Applications 


This  chapter  describes  how  to  install  and  prepare  your  system  for  your 
FMS-11  application  program.  The  four  main  topics  are:  | 

1.  RSX  system  generation  options 

2.  FMS  installation  procedures 

3.  FMS  configuration  procedures 

4.  IAS  procedures 

(There  are  no  system  generation  options  for  using  FMS-11  on  IAS  systems.) 

8.1    RSX  System  Generation  Options 

With  RSX-llM  and  RSX-llM-PLUS  systems,  the  Form  Driver  depends  on 
terminal  service  and  mapping  features  that  you  can  select  only  when  you 
perform  the  system  generation  procedure. 

8.1.1  Terminal  Service  Option 

With  RSX-llM  v3.2,  the  full  duplex  terminal  driver  is  the  driver  that  is  built 
into  your  system  by  default.  You  can  run  all  FMS  software  with  the  full 
duplex  terminal  driver,  and  the  Form  Editor  requires  that  driver.  The  full 
duplex  terminal  driver  must  include  support  for  get  multiple  characteristics 
and  set  multiple  characteristics.  However,  to  provide  support  for  FMS  appli- 
cations on  RSX-US  systems  and  RSX-llM  systems  that  are  unmapped,  you 
can  also  build  the  Form  Driver  to  run  with  th  '  older,  half  duplex  terminal 
driver.  If  the  half  duplex  terminal  driver  is  usc^,  it  must  provide  support  for 
unsolicited  input  character  AST  and  transparent  read  and  write. 

8.1.2  Mapping  Options 

Most  FMS  users  build  and  use  mapped  RSX-llM  and  RSX-llM-PLUS 
systems.  Mapped  systems  are  used  because: 

1.  Mapped  systems  provide  much  more  memory  iv)r  applications  than  un- 
mapped systems  do. 

2.  The  FMS  Form  Editor  and  Form  Utility  require  a  mapped  system. 

3.  Using  one  system  for  all  FMS-related  work  is  more  convenient  than  using 
two  systems  for  different  parts  of  the  work. 
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However,  you  can  also  build  and  use  unmapped  systems  for  your  FMS  appli- 
cations. In  general,  the  Foriii  Driver  modules  and  your  programs  will  work 
properly.  Because  the  Form  Driver  requires  approximately  7500.  (decimal) 
bytes  of  memory,  you  have  to  limit  the  size  of  your  FMS  program  to  the 
amount  of  memory  that  remains  free  for  applications. 


8.2    System  Installation  Procedures 

To  install  all  of  the  FMS  components,  including  the  Form  Driver  modules, 
you  have  to  execute  the  indirect  command  file  FMSINS.CMD  to: 

1.  Copy  the  distribution  files  from  the  distribution  volumes  to  the  system 
volumes. 

2.  Task  build  all  FMS  utilities. 

3.  Compile  and  task  build  the  demonstration  programs. 

8.2.1    The  RSX  Procedure 

In  order  for  the  installation  to  successfully  complete,  you  must  be  logged  in 
under  a  privileged  account.  If  you  are  installing  FMS- 11  on  an 
RSX-llM-PLUS  system,  your  terminal  must  be  set  for  MCR  mode  com- 
mands. It  is  assumed  that  FMS-11  is  being  installed  on  the  system  device.  All 
FMS-11  files  are  moved  into  account  [30.10].  A  VTlOO  is  required  to  run  the 
Form  Editoi  and  the  demonstration  programs. 

Approximately  3600  disk  blocks  are  required  to  install  FMS-11/RSX. 

In  the  installation  procedure  detailed  below,  the  parameter  'ddn'  is  the  name 
and  unit  number  for  the  device  FMS-11  is  being  installed  on.  The  parameter 
'deu'  is  the  name  and  unit  number  of  the  device  on  which  the  distribution 
media  is  mounted  on. 

INSTALLATION  PROCEDURE: 


MCR>ASN  ddn=S\': 

MCR>UFD  ddn:l30  .10] 
MCR > SET  /UIC^[30.10] 


'  MaKe  the  i  n  s  t  a  1  1  a  t  i  ori  den  ice 

'  the  d  e  t  a  LI  1  t  s  v  s  I  e  rn  device 

'  Create  the  UFD  for  FMS-11 

I  Set  the  default  L I C 


For  magnetic  tapes  on  RSX-UM: 


MCR  >  ALL    drr: 

MCR>FL;;    SY:  =f/rc;FMSINS  .CMD/DO 


!     Allocate    the    liri^e 

'     Copy     1  ri  5  t  a  1  1  a  t  1  0  ii     comma n  d 

I     file 


For  magnetic  tapes  on  RSX- II M  PLUS: 


MCR>MOU  deu:/FOR 

MCR/FL;;    SY:  ^de-  :FM3ING.CriD/D0 


'     Mou.it    'ape    as    foreisn    denic*? 
'     C  0  F-  v     in  5  t  a  1  1  a  t  1  0  ii    comma  n  d 
;     file 
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For  disks  on  both  systems: 


MCR:   ■     'I     deii:FMSRS>; 

MCR;  PIP    SY  :  /NV  =  de','  :FM3INS  .  CMD 


'     M  0  LI  n  t     the     'd  i  5  K 
'     Copy     1  ri  s  t  a  1  1  a  t,  1  0 1 
I     file 


c  0  III  (II  a  ri  d 


For  all  media: 


MCR>3PMSINS 


I     C  0  F  /'     files     f  r  0  (Ti    distribution 
I     media    a  n  d    b  u  1  1  d    utilities 
p  r  0  3  r  a  (II  s 


a  ri  d     ij  e  m  0 


The  installation  command  file  prompts  for  the  distribution  device.  The 
FMS-11  files  are  copied  to  account  [30,10]  on  the  system  device.  The  Form 
Editor  (FED)  and  the  Form  Utility  (FlIT)  are  task  built.  The  MACRO  ver- 
sions of  the  demonstration  program  are  built  automatically.  The  COBOL 
BASIC-PLUS-2,  FORTRAN  IV,  and  FORTRAN  IV-PLUS  versions  of  the 
demonstration  program  are  built  only  if  the  corresponding  compilers  are  in- 
stalled in  the  system.  If  the  FORTRAN  IV-PLUS  compiler  is  installed  in  the 
system,  it  is  assumed  that  the  file  LB:[1,1]F4P0TS.0LB  exists  as  the  FOR- 
TRAN IV-PLUS  OTS.  The  installation  command  file  asks  the  user  if  this  is 
the  case.  If  not,  the  FORTRAN  IV-PLUS  versions  of  the  programs  cannot  be 
built. 


8.2.2   The  IAS  Procedure 

Log  in  to  a  privileged  account.  You  must  be  in  a  privileged  account  to  run  the 
command  file  FMSBLD.CMD.  (See  the  IAS  System  Management  duide  for 
details  on  privileged  accounts.) 

The  installation  command  file  FMSINS.CMD  assumes  that  your  installation 
kit  is  mounted  in  drive  0.  (MMO:  is  the  assumed  device  xor  a  tape  installation 
kit.)  If  this  is  not  true,  edit  FMSINS.CMD  to  reflect  the  correct  installation 
device. 

Approximately  3600  disk  blocks  are  required  to  install  FMS-11  on  IAS. 

In  the  installation  procedure  detailed  below  the  parameter  'ddn'  is  the  name 
and  number  of  the  device  on  which  you  are  installing  FMS  11.  The  parameter 
'dev'  IS  the  name  and  number  of  the  device  on  which  the  distribution  media  is 
mounted.  The  parameter  'volumeident'  identifies  the  volume  for  handling  by 
the  operator  (lor  example,  a  label  written  on  the  volume  container).  pA-en  \i 
you  u.se  the  /OVERRIDE  or  /OVR  qualifiers,  you  must  supply  a  volume  iden- 
tification that  is  between  1  and  12  characters  long. 

INSTALLATION  PROCEDURE: 

For  magnetic  tapes: 


|««rR>MQU  deu  : /CHA--CFCR] 

MCR  >  P  LK  S  Y  :  [  1  .  1  ]  -  rj  e  ,,  :  [  1  ,  n  FMS  1  NS  .  C  MD 

MCR>@[  1  •  1  ]FMS1NB 


'  Mo  '.in  t  the  n  0  1  ume 
'  Copy  installation 

c  0  (i\  (II  and    file 
!     I  ri  11  0  K  e     1  ri  5  t  a  1  1  a  t  1  0 1 

c  0  (II  III  a  rnd     file 
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or 


SCI > MOUNT /FOREIGN  deu-  FMSKIT 
SCI > COPY  DEU :  [ 1  .  1  3 FMS  I  NS . CMD - 
.'DOS  [1  ,!]♦.* 
SCI > INS  TALL /SYS:  IND  [  1  1  .1 ]  IND 

SCI  >  IND  @[ 1  .  1  ]FMSINb 


M  0  Li  n  t  the  m  o  1  u  m  e 
C  0  p  v  installation 
c  0  (II  m  and  file 
I  ri  5  t  a  1  1  indirect 
c  0  m  (II  and  file  t.  a  ?  t; 
I  n  M  0  K  e  1  n  5  t  a  1  1  a  t  1  o  n 
c  0  (It  (II  a  ri  ij  file 


For  disk  distribution: 


MCR>MOU  deMi/O'.'R 

MCR>PIP  SY:/Ni.i=dew  :  [  1  ,  i  1FMSINS.CMD 

MCR>@[  1  -1  ]FMS1NS 


I  M  0  u  Vi  1  the  d  1  s  K 

I  C  0  p  V  1  n  s  t  a  1  1  a  1 1  0  ri 

c  0  (It  (ii  a  Ti  id  file 
!  I  n  1.1  0  K  e  installation 

c  0  (ii  m  and  file 


or 


SCI  >MOUNT/0'.'ERrvTDE:i.'OL  de>':  FMSKIT 
SCI  >  COPY  de'.' :  [  1  .  lIFMSINS.ChD  #.* 

SCI > INST ALL /SYS: IND  [11 .U IND 

SCI >  IND  @[ 1  ,  1  IFMSINS 


M  0  i.i  n  t  the  d  i  s  K 
C  0  p  >'  installation 
c  0  (H  (Ti  and  file 
Install  1  n  d  1  r  e  c  t 
c  0  (I)  (II  a  n  d  file  t  a  s  K 
I  n  i»  0  K  e  1  n  s  t  a  1  1  a  t  1  0  n 
c  0  (II  (ii  a  n  d  file 


The  system  copies  all  files  and  builds  FMS-11. 

The  Form  Editor  (FED)  and  the  Form  Utility  (FUT)  are  task  built.  The 
MACRO  versions  of  the  demonstration  program  are  built  automatically.  The 
COBOL,  BASIC-PLUS-2,  FORTRAN  IV.  and  FORTRAN  IV-PLIIS  versions 
of  the  demonstrai  i  program  are  built  only  if  the  corresponding  compilers  are 
installed  in  the  system.  If  the  FORTRAN  IV  compiler  is  installed  in  the 
system,  it  is  assumed  that  the  file  LB:[11]F0R0TS.0LB  exists  as  the  FOR- 
TRAN IV  OTS.  If  the  FORTRAN  IV-PLUS  compiler  is  installed  in  the  sys- 
tem, it  is  assumed  that  the  file  LB:(l,llF4P0TS.0LB  exists  as  the  FOR- 
TRAN IV-PLUS  OTS.  The  installation  command  file  asks  the  user  if  this  is 
the  case.  If  not,  the  FORTRAN  IV-PLUS  versions  of  the  programs  cannot  be 
built. 

8.3    Configuration  Procedure  for  the  Form  Drivei' 

The  Form  Driver  has  several  features  that  you  may  want  for  some  of  your 
applications  but  not  for  all  of  them.  For  example,  if  you  are  using  forms  that 
include  fixed  decimal  fields,  you  must  use  a  version  of  the  Form  Driver  that 
provides  fixed  decimal  field  support.  Otherwise,  since  fixed  decimal  field 
support  increases  the  size  of  the  Form  Driver  by  about  200  words,  you  may 
want  to  use  a  smaller  version  of  the  Form  Driver. 

The  configuration  procedure  for  the  Form  Driver  uses  a  straightforward  in- 
teractive dialogue  that  asks  the  following  questions: 

•  Do  you  want  to  build  the  Form  Driver  without  the  SOB  instruction? 

•  Do  you  want  ONLY  memory  resident  form  support? 
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• 


•  Do  you  want  to  delete  fixed  decimal  field  support? 

•  Do  you  want  to  delete  scrolled  area  support? 

•  Do  you  want  debug  error  messages? 

•  Do  you  want  support  for  the  VT52  terminal  instead  of  the  VTIOO? 

•  Size  of  the  directory  buffers  in  blocks? 

•  Number  of  directory  buffers? 

•  Number  of  libraries  open  at  a  time? 

•  Do    you    want    support    for    other    than    full    duplex    terminal    service? 
(RSX-UM/M-PLUS  only) 

To  run  the  configuration  procedure  dialogue,  the  FMS  software  must  be  in- 
stalled on  your  system.  The  followmg  commands  invoke  the  procedure: 

For  RSX-llM  and  RSX-UM-PLUS  - 

mcr:>@fdi.ibld®1T) 


For  IAS  - 


MCR     @[  1  1  ,1  IGjFDi.'BLD'RETj 


or 


SCI >  INSTALL 'SYS:  IND  [  1  1  .  1  ] IND 
SCI >  IND  @[  1  1  ,  1  1G]FDUBLD 


8.3.1    Question  Types  and  Defaults 

The  configuration  dialogue  uses  two  types  of  questions: 

1.  Yes-No  questions. 

2.  Questions  that  ask  you  to  type  a  number. 

For  any  question,  you  can  ask  for  a  short  explanation  of  the  question  by  typing 
the  Escape  key  in  response  to  the  question.  After  an  explanation,  the  system 
displays  the  current  question  again. 

Yes-No  questions  are  in  the  following  form: 

>    #    Text     of     the    q  u  e  s  t  i  o  ri  "^       [  Y  /  N  ] 

You  can  respond  as  follows: 

1.  Type  the  F^scape  key  if  you  want  an  explanation. 

2.  Type  \'  and  press  the  Return  key  for  YES. 
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3.  Type  N  and  press  the  Return  key  for  NO. 

4.  For  the  default  response,  press  the  Return  key  without  typing  another  key. 
The  default  to  all  Yes-No  questions  is  NO. 

Questions  that  ask  you  to  type  a  value  are  in  the  following  form: 

>    *    Text    of     the    qi.iestiori     [D    R:k-v'    D:z]: 


In  the  configuration  dialogue,  all  numeric  responses  are  in  decimal.  In  the 
model  above,  the  first  letter  D  in  the  brackets  stands  for  decimal.  The  second 
field  within  the  brackets  shows  the  range  of  valid  answers.  In  the  model 
above,  R:  stands  for  range,  x  stands  for  the  smallest  valid  answer,  and  v 
stands  for  the  largest  valid  answer.  The  third  field  within  the  brackets  shows 
the  default  value.  In  the  model  above,  D:  stands  for  default,  and  z  stands  for 
the  default  value. 

You  can  respond  as  follows: 

1.  Type  the  Escape  key  if  you  want  an  explanation. 

2.  Type  a  number  that  is  within  the  specified  range  and  press  the  Return 
key. 

3.  For  the  default  response,  press  the  Return  key  without  typing  another  key. 

"1  he  following  sections  explain  each  of  the  configuration  dialogue  questions. 
Each  section  begins  by  quoting  the  short  explanation  that  the  system  displays 
if  you  type  the  Escape  key  in  response  to  the  question. 


8.3.2    Do  You  Want  to  Build  the  Form  Driver  without  the  SOB 
Instruction?  lY/N): 


"Normally  the  Form  D r i w e r  i5  built  to  taKe  aduantaSe  of 
the  h  a  r  ij  w  a  r  e  SOB  i  ri  s  t  r  u  c  t  i  o  ii  .  H  o  ui  e  m  e  r  »  for  those  PDP-11 
processors  uihich  do  not  support  the  SOB  instructioi'it  the 
Form  Driller  c  a  ii  be  built  to  use  a  macro  instead  (  a  d  d  i  ii  a 
a  t'  0  u  t  5  0  i«i  0  r  d  s  to  its  size)." 


8.3.3    Do  You  Want  ONLY  Memory  Resident  Form  Support? 
lY/NJ: 

"Normal  I'/'t  the  Form  Drinrir  ha?  support  for  both  memory 
resident  a inj  media  r  e  s  i    t  f  o  r  ii\  s  .  For  an  application 
running  under  RS);-11S  t        'hich  for  other  reasons  must 
r  u  n  1  n  m  i  m  i  n  a  1  m  e  m  o  r  y  >  select  0  N  L  'i'  m  e  m  o  r  y  r  e  s  i  d  e  ri  t  for  m 
support  to  sa«ie  space." 

Section  5.4  explains  how  to  include  m.emory  resident  forms  with  your  pro- 
grams. 
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8.3.4    Do  You  Want  to  Delete  Fixed  Decimal  Field  Support? 
[Y/Nl: 


"If  memory  space  is  i.»  e  r  y  critical  a  ri  id  fixed  d  e  c  i  nt  a  1 

f  1  "?  1  'd  s  a  !■  e  not  i"i  e  e  id  e  d  t  a  b  o  u  t  2  0  0  words  can  t'  e  s  a  u  e  d  b  v 

d  e  1  e  t  1  i-i  d  s  I.I  p  p  0  r  t  for  fixed  decimal  fields." 


Chapter  2  explains  fixed  decimal  fields.  If  you  do  not  know  whether  fixed 
decimal  fields  appear  in  any  of  the  forms  that  you  are  using,  use  the  Form 
Utility  to  get  a  printable  description  of  each  form  and  check  each  field  de- 
scription. Chapter  3  describes  how  to  use  the  Form  Utility. 

8.3.5    Do  You  Want  to  Delete  Scrolled  Area  Support?  [Y/N]: 


"If  m  e  rn  0  r  y  space  is  very  critical  a  ri  d  scrolled  areas  are 
n  0  t  n  e  e  d  e  d  »  a  ti  o  u  t  5  0  0    words  c  a  ri  ti  e  s  a  w  e  d  b  v  d  e  1  e  t  i  n  a 
support  for  scrolled  areas." 

Chapter  2  describes  how  to  create  a  scrolled  area  within  a  form,  and  Chapter  7 
illustrates  how  to  use  scrolled  areas.  If  you  do  not  know  whether  any  of  the 
forms  that  you  are  using  contain  scrolled  areas,  use  the  Form  Utility  to  get  a 
printable  description  of  each  form  and  check  each  field  description.  Chapter  3 
describes  how  to  use  the  Form  Utility. 


8.3.6    Do  You  Want  Debug  Error  Messages?  [Y/NJ: 


"While  d  e  b  u  3  3  1  ri  3  an  application-  it  is  n  e  r  v  h  e  1  p  f  li  1  to 
hane  the  Form  DriMer  sianal  errors  iri  the  application 
code  at  the  terminal.  Once  a  ri  a  p  p  1  i  c  a  t  i  o  ri  is  d  e  b  1 1  d  3  e  d  »  a 
Form  D  r  1  *' e  r  without  this  support  should  be  used  to  sai'e 
space  arid  to  auoid  hauiriS  these  messaaes  appear  to  oper- 
ators." 


Chapter  5  describes  the  debug  error  message  features.  Appendix  C  includes  all 
of  the  messages. 

8.3.7    Do  You  Want  Support  for  the  VT52?  |Y/N|: 


"The  Form  DrM'er  was  designed  to  taKe  adiiantaae  of  the 
features  of  the  '.'TlOO  terminal.  Howeiier>  it  is  possible 
to  build  a  Form  Driver  to  support  the  ','T52  terminal.  A 
smale  Form  D  r  i  u  e  r  library  can  support  either  the  VTIOO 
or  t  It  e  '.'  T  5  2  but  not  both.  I  ri  order  to  j  ..i  p  p  o  r  t  both  t  v  p  e  s 
of  t  e  r  m  1  i"i  a  1  5  t  y  o  u  must  m  a  i  I'l  t  a  1 1 1  two  Form  D  r  1 1 1  e  r  li- 
braries. 


8.3.8    Size  of  the  Directory  Buffers  in  Blocks  |D  R:1.-2.  D:1.|: 


"  0 11  e  b  1  0  c  K  buffers  provide  for  form  libraries  with  c  ti  o  u  t 
GO  forms.  T  i.p  o  b  1  o  c  t;  ti  u  f  f  e  r  s  provide  for  1  i  ti  r  a  r  i  e  s  with 
about  1 20  forms. 
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Form  library  files  and  the  directory  butters  that  they  require  are  needed  only 
when  you  are  using  media  resident  forms.  Therefore,  if  you  select  only 
memory  resident  forms  in  the  first  configuration  dialogue  question,  the  system 
does  not  ask  you  this  question  or  the  questions  that  are  described  in  the  next 
two  sections. 

The  size  to  use  for  directory  butters  depends  on  several  factors.  A  one  block 
directory  buffer  is  large  enough  for  a  BO-form  (decimal)  ibrm  library  and  a  two 
block  buffer  is  large  enough  for  a  124-f()rm  (decimal)  form  library  file.  Each 
form  library  file  directory  must  reside  in  one  directory  buffer.  When  a  direc- 
tory is  larger  than  the  buffer  size  you  have  specified,  only  the  forms  for  the 
part  of  the  directory  that  fits  can  be  accessed.  When  the  F'orm  Driver  at- 
tempts to  access  a  form  lor  which  there  is  no  directory  entry  the  Form  Driver 
signals  that  it  cannot  find  the  Ibrm. 

The  size  of  the  directory  buffer  is  also  the  size  of  the  buffer  for  reading  forms. 
Larger  buffers  allow  faster  access  to  forms  because  fewer  I/O  requests  are 
required  to  read  the  form  description.  Space  can  be  saved  by  allocating 
smaller  buffers.  The  default  directory  buffer  size  is  one  block. 

8.3.9    Number  of  Directory  Buffers  [0  R:1.-20.  D:1.|: 


"The     lime     r  e  q  i.i  i  r  e  d     to     access     f  o  r  in    directories    w  a  /    be     op- 
timized   by    (eepina    ijirectories     for    more     fordi     litiraries 
1  ri    ill  e  w  0  r  >•     at     the    e  k  p  e  ri  s  e    of    m  e  rn  o  r  v     space.     0  ri  1  v     o  ri  e    di- 
rector/    buffer     IS    e  I'  e  r     required.     Buffers     are    made     a  u  a  i  1  - 
a  t'  1  e    oil    a     1  e  a  s  t  -  r  e  c  e  n  t  1  ,■  -  m  s  e  'j    basis. 

The  number  ot  directory  buffers  depends  on  several  factors.  Space  can  be 
reduced  by  allocating  fewer  l)ulfers.  but  time  to  access  form  libraries  is  in- 
creased. With  only  o  le  directory  l)ulTer.  you  can  use  any  number  of  form 
library  files  simultaneously.  The  directories  are  read  and  reread  as  needed. 
Time  to  access  form  libraries  is  decreased  by  allocating  more  directory 
buffers,  but  the  amount  of  space  used  is  increased. 

When  you  are  ".sing  more  form  library  files  than  the  number  of  directory 
buffers  you  have  allocated,  the  directory  buffers  are  reallocated  on  a  least- 
recent  ly-user'  basis  to  optimize  the  directory  buffer  usage.  When  RMS  sup- 
port is  selected,  sufficient  pool  space  is  allocated  for  simultaneous  use  of  as 
many  form  lil)ras"y  tiles  as  you  have  specified.  The  following  seition  descril)es 
how  to  specify  the  number  of  form  library  files  that  you  will  be  using  simulta- 
neously. A  one  block  buffer  is  also  allocated  lor  the  open  code  of  RMS  to  use. 


m 


8.3.10    Number  of  Libraries  Open  at  a  Time  (D  R:1.-20.  D:1.|: 


"Select  the  m  a  x  i  m  u  i!i  n  umber  of  for  m 
be  open  at  the  same  time." 


libraries  l'  h  i  c  h  must 


Successive  libraries  are  opened  by  changing  the  channel  to  the  required  argu- 
ment block.  This  channel  corresponds  to  the  logical  unit  number  (Ll'N)  that 
is  assigned  'ly  the  t  ^  k. 


n 
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8.3.11    Do  You  Want  Support  for  Other  than  Full  Duplex 
Terminal  Service?  [Y/N]  (RSX-11M/M-PLUS  only): 

"If  the  application  is  to  run  under  RSX-l  3  or  in  an  un 
mapped  R  S  )<  -  1  1  M  s  v  s  t  e  di  or  is  u  e  r  v  space  critical-  m  e  m  o  r  v 
can  be  saned  bv  not  usind  the  full  duplex  terminal 
driver.  If  the  application  is  u  s  i  ri  3  another  t  e  r  id  i  r,  a  1 
d  r  1  M  e  r  »  the  Form  D  r  i  u  e  r  (n  li  s  t  ti  e  reconfigured  to  operate 
The  terminal  driver  used  must  h  a  u  e  support  for  u  ri  s  ci  1  i  - 
cited  1  ri  p  I.I  t  AST's. 


The  RSX-UM/M-PLUS  I/O  Drivers  Reference  Manual  describes  the  full 
duplex  and  half  duplex  terminal  drivers  in  detail. 

For  all  systems:  After  you  have  answered  this  question,  the  system  displays     | 
the  following  notice. 


"There  are  ri  o  more  questions.  It  ut  i  1  1  t  a  K,  e  a  f  e  li  m  i  n  u  t  e  s 
to  assemble  the  Form  Driver  and  build  the  object  li- 
braries. " 


At  the  end  of  the  confifjuration  procedure,  the  svstem  produces  the  following 
files  in  [.30,101  for  RSX-llM/M-FLUS  and  LB:il,l]  for  IAS:  | 

•  FMSMAC.MLB,  the  FMS  macro  library. 
For  VT-100  support: 

•  FDVLIB.OLB,  the  Form  Driver  library  for  applications  that  use  FCS  sup- 
port . 

•  FDVLRM.OLB,  the  Form  Driver  library  for  applications  that  use  RMS 
support. 

For  VT-52  support: 

•  F.'i2LIB.()LB,  the  Form  Driver  library  for  applications  that  use  FCS  sup- 
port. 

•  F.^2LRM.0LB.  the  Form  Driver  library  for  applications  that  use  RMS  sup- 
port . 


8.4    Building  and  Running  Your  Application  Tasl<s 


# 


8.4.1    Bullcfing  and  Running  Application  Proy^^ams 

Application  programs  written  in  supported  languages  are  built  using  the  task 
builder  in  the  norma!  way.  In  this  chapter,  the  separate  sections  for  each 
supported  language  include  examples  of  task  build  procedures. 
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The  high  level  language  interface  object  modules  (in  LB:[11,116]  for  IAS) 
supplied  are: 

•  HLLFOR.OBJ  the  interface  for  FORTRAN  IV  and  FORTRAN  IV-PLUS. 

•  HLLBP2.0B-J  the  interface  for  BASIC-PLUS-2. 

•  HLirOB.OBJ  the  interface  for  COBOL-11. 


I 


I 


8.4.2    Considerations  When  Using  ODL 

A  few  considerations  must  be  followed  when  including  the  Form  Driver  in  an 
ODL  structure. 

The  data  module  must  always  be  in  the  root.  To  put  it  there,  use  a  module 
specification  like  the  following. 

For  RSX  systems: 

FD'.'LIS  'LB:FD'.'DhT 

For  IAS  systems: 

LB  :  [  I  .1  IFD'.'L  IB.'LB  :PD'.'DAT 

With  the  full  duplex  terminal  driver,  the  Form  Driver  may  be  placed  on  any 
branch  of  the  ODL  by  using  a  module  specification  like: 

For  RSX  systems: 

FD'.'LIB/LB  :FDU-FDULIB-  LB 

For  IAS  systems: 

LB:  [  1   .1  ]FD'.'LI3/LB  :FDM-LD:  T  i  .  1  ]FDULIB /LB 

With  the  half  duplex  terminal  driver,  such  as  may  be  used  in  applications 
running  under  RSX-US,  the  following  Form  Driver  factor  must  be  included 
in  the  root: 

For  RSX  systems  (not  applicable  to  IAS): 

FD'.'L  IB  '•LB:FD'.'T  10 

The  language  interface  modules  should  be  placed  with  the  P'orm  Driver  li- 
brary by  using  a  specification  like: 

For  RSX  systems: 

FORM:        .FCTft    HLLCIM.  -  FD'.'L  I  B  /  LB  :  FDU  •  TDVL  I  B  '  LB 
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For  IAS  systems: 


FOrvM:  .FCTR  [11  .  1  1  G  ]  HLLCOB  -  L6  :  [  1  .  1  ]  FDUL  I  B  /  L  B  :  FD'.»  ■ 
LB:  [ 1  .1  JFDULIB/LB 


8.5    Running  FMS-11  Applications  Under  IAS 

When  running  FMS-11  applications  under  IAS,  you  must  set  your  terminal's 
characteristics  to  allow: 

•  Deferred  processing  read-ahead  (TC.RAT) 

•  Seven  bits  passed  for  read-pass-all  (TC.P8B) 

•  tWsj  and  ^trloj  synchronization  (TC.CSQ) 

You  set  your  terminal  with  the  following  commands: 

PDS>SET  TER  READ:DEF  NOPASSALL  CONTROLS 


or 


MCR>TER  . READ:  DEF/ NO PASS ALL /CONTROLS 

Alternatively,  an  application  task  written  in  MACRO-11  can  execute  the 
10. SMC  QIO  function  to  set  the  terminal  characteristics  described  above.  An 
application  task  written  in  FORTRAN  can  use  the  FORTRAN  special  subrou- 
tine WTQIO  to  set  the  terminal  characteristics  described  above.  For  more 
details  see  the  IAS  Device  Handlers  Reference  Manual. 


Preparinp  Your  System  for  FMS-11  Applications    8-11 

May  1981 


Appendix  A 

The  FMS  System  MACRO  Library 


,NLIST 


.ENABLE  LC 

LIST 

TITLE 

FMSMAC   -  FMS  Macro  Library 

SBTTL 

************************************ 

SBTTL 

*                                 * 

SBTTL 

*               FMSMAC               * 

SBTTL 

*         .IDENT   /vol. 00/           * 

SBTTL 

*                                    * 

SBTTL 

************************************ 

SBTTL 

IDENT 

/vol. 0  0/ 

COPYRIGHT  (C)  1979  BY 
DIGITAL  EQUIPMENT  CORPORATION,  MAYNARD ,  MASS, 


MODULE:         FMSMAC. MAC 

VERSION:        VOl.OO 

AUTHOR:        Larry  Pearson 

DATE:           20-Oct-78 

MODIFIED  BY: 

DARRELL  DUFFY  (DJD) 

17-NOV-78 

DJD 

4--APR-79 

DJD 

lO-APR-79 

DJD 

l-MAY-79 

DJD 

Cheryl  Vedoe 

5-NOV-79 

CAV 

MOVE  TO  RSX-llM  AND  NAME  FMSMAC 
CHANGE  $PRINT  ROUTINE  TO  $FMSPR 
CHANGE  $FLUSH  ROUTINE  TO  $FMSFL 
CHANGE  ;FLUSH  MACRO  TO  $TTFLS  TO 
AVOID  CONFLICT  WITH  RMS-11 


Change  NEWC$P  references  to  support 
SOB  instruction. 


$ARTS 


Issues  a  .MCALL  for  other  commonly  used  MACROS 


MACRO 

$ARTS 

.MCALL 

$SAV20, 

$SAV30, 

$SAV50, 

BSECT 

.MCALL 

ORIGIN, 

PSECT, 

FSYMS, 

NEGCOD 

.MCALL 

$TTYIN, 

STTINR, 

$PRINT, 

$TTFLS 

.MCALL 

$TTYOUT 

IIP 

NDF,NEWC$P, 

NEWCSP 

=  0 

IIF 

NE,NEWC$P, 

.MCALL 

SOB 

ENDM 

SARTS 

;CAV 
;CAV 


A-I 


;  + 

;  $SAV20 


SAVE  REGISTERS  2-0 


.MACRO    $SAV20 

JSR      R2,$SAV20 
.ENDM     $SAV20 

;  + 

;  $SAV30 

» 

i  SAVE  REGISTERS  3-0 


•MACRO    $SAV30 

JSR      R3,$SAV30 
.ENDM     $SAV30 

?  + 

;  $SAV5  0 

• 

;         SAVE  REGISTERS  R5-R0 

m 
t 

t" 

•MACRO    $SAV50 

JSR      R5,$SAV50 
•ENDM     $SAV50 


+ 
SOB 


A  software  substitute  for  the  SOB  instruction  for  old  PDP-lls. 


;- 


MACRO    SOB  R,A 

DEC  R 

BNE  A 
,  ENDM     SOB 


++ 
Documentation  of  use  of  ORIGIN  and  PSECT 

ORIGIN  Section_name,List_of_Attr ibutes 
This  defines  the  default  •PSECT 

PSECT   Sect ion_ name, List_of  Attributes 

This  changes  to  a  .PSECT  (perhaps  unnecessary) 

;         PSECT    * 

This    reverts   back    to   the    last    .PSECT    referenced   with 
the   ORIGIN   macro. 
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UNORG 


or  internal  use  only, 
PSECT. 


Normally  defined  by  ORIGIN  and  invoked  by 


,  MACRO 
,  ENDM 


UNORG 
UNORG 


;  ORIGIN 


Defines  the  PSECT  to  revert  back  to  with  PSECT  * 


MACRO 

ORIGIN 

SECT, LIST 

MACRO 

UNORG 

LIST 

BEX 

PSECT 

SECT,<LIST> 

ENDM 

UNORG 

PSECT 

<SECT>  ,<LIST> 

NLIST 

BEX 

ENDM 

ORIGIN 

PSECT 


Changes  to  a  specified  .PSECT  or  reverts  back  to  the  one  defined 
by  ORIGIN  when  PSECT  *  is  used. 


.MACRO 

PSECT 

SECT, LIST 

.LIST 

BEX 

.  IF 

IDN 
UNORG 

SECT,<*> 

.NLIST 

BEX 
.MEXIT 

.IFF 

•  IF  NB 

<LIST> 

.PSECT 

SECT, LI 

ST 

.IFF 

.PSECT 

SECT 

.ENDC 

.ENDC 

.NLIST 

BEX 

•  ENDM 

PSECT 
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SERROR 


Print  error  message 


.MACRO   TERROR  LVL,TXT 

.GLOBL  $ARTEH 

PSECT  .TEXT.  ,  ■:D-> 

.  .A 

.ASCIZ  \' LVL'- 'TXT'\ 

PSECT  * 

JSR  H4,$ARTER 

.WORD  . .A 

.ENDM    $ERROR 


BSECT 


BS 


Lefino  bit  oriqin  for  bit  definitions.   This  MACRO  is  normally  used 
in  coniuntion  with  the  BS  MACRO. 


Defines  the  specified  symbol  as  equivalent  to  the  current  bit  position 
and  increments  the  bit  counter  to  the  next  position. 


MACRO    BSECT    SECTNM , ARC  ,  INIT 


•MACRO 

BS       ARG1,GBL 

.  IF 

NB       <ARG1> 

.  IF 

B        <'GBL> 

.LIST 

ARGl  =  SECTNM 

.NLIST 

.IFF 

.LIST 

ARGl  ==  SECTNM 

.NLIST 

.ENDC 

.ENDC 

SECTNM  =  SECTNM  *  2 

.ENDM 

BS 

.IIF 

NDF, SECTNM,  SECTNM  =  0 

.  IIF 

NB        <INrr>,  SECTNM 

.  IF 

rJB       ■  ARG  ' 

.  IF 

NE        ^ARG> 

.REPT  ARG 

BS 

•  ENDR 

.ENDC 

.ENDC 

.ENDM 

BSECT 

;  + 

;  NEGCOD 

; 

Define  negative  'Todes 

• 

with  the  NC  macro. 

»- 

Normally  used  in  conduction 
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NC 


Defines  a  specfied  symbol  as  equivalent  to  the  current  value 
of  the  section  name. 


.MACRO    NEGCOD   SECTNM , ARG , INIT 


.MACRO    NC       ARG1,GBL 
.IF       NB,<ARG1> 
.IF     B,<GBL> 

.LIST 

ARGl  =  SECTNM 

.NLIST 


IFF 


.ENDC 
.ENDC 
SECTNM 
.ENDM 


I  IF 
I  IF 
IIF 


.LIST 

ARGl  ==  SECTNM 

.NLIST 


=  SECTNM  -  1 
NC 


NDF, SECTNM,  SECTNM  =  0 
NB,^INIT>,  SECTNM  =  -1 
NB,^ARG>,  SECTNM  =  -<ARG> 


ENDM 

+ 
FSYMS 


.MACRO 

TESXT 

FISELD 

NASMED 

EFSORM 

.ENDM 


NEGCOD 


This  macro  defines  some  form  definition  symbols 


FSyM$ 


FSYM$ 


-2 
-3 
-4 

-5 


;  STTFLS 

f 

> 


Clear  the  input  ring  buffer  of  characters. 


MACRO    $TTFLS 

CALL     $FMSFL 
,  ENDM     $TTFL" 
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;  $PRINT 


Print  a  string  of  text 


MACRO 

$PRINT 

ADDR 

.GLOBL 

$FMSPR 

IF 

NB 

<ADDR> 

IF 

DIP 

<ADDF> ,R0 

MOV 

ADDR,RO 

ENDC 

ENDC 

CALL 

SFMSPR 

ENDM 

SPRINT 

$TTYIN 


IF 
IF 


ENDC 
ENDC 
ENDM 


Input  a  character  from  the  terminal 


, MACRO    STTYIN   CHAR 


CALL     $CHRIN 


NB 

DIP 

MOVE 


STTYIN 


<CHAR> 
<.CHAR>  ,R0 
RO  ,CF-!AR 


$TTINR 


Input  a  character  from  the  terminal  without  waiti 


ng 


• 


,MACRO    $TTINR   CHAR 


IF 
IF 


CALL 
NB 
DIP 
MOVB 


STTINR 
<CHAR^ 
<CHAR> ,R0 
RO  ,CHAR 


ENDC 
ENDC 
ENDM     STTINR 


$TTYOUT 


7" 


IF 
IF 


ENDC 
ENDC 


Output  a  character  to  the  terminal 


.MACRO    $TTYOUT  CHAR 


NB 

DIF 

MOVB 


<CHAR> 
<CHAR> ,R0 
CHAR,RO 


CAr-L     $CHROU 


ENDM     $TTYOUT 
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FORM  DRIVER  CALL  MACRO 

$FDV  ARGLST,FNC , REQ , NAM  ,  NUM , TRM , VAL , LEN 

ARGLST  OPTIONAL  POINTER  TO  ARGUMENT  LIST 

FNC  REQUIRED  COMMAND  FUNCTION  CODE  (LAST  3  LETTERS] 

REQ  -  LEN       OPTIONAL  KEYWORD  ARGUMENTS  TO  SUPPLY  ARGtr.'.ENTS 


MACRO    $FDV  ARG , FNC, REQ, NAM, NUM, TRM, VAL, LEN 


MACRO 


$$FA  KWD,THG 


IF  NB,THG 


MOV 


.ENDC 
.ENDM 
.IF  NB,ARG 

MOV 
.ENDC 

$$FA  F$REQ,<REQ> 
$$FA  F$NAM,<NAM> 
$$FA  F$NUM,<NUM> 
$$FA  F$TRM,<TRM> 
$$FA  F$VAL,<VAL> 
$$FA  F$LEN,<LEN> 


THG,KWD(RO) 


ARG.RO 


IF  NB,FNC 


ENDC 
ENDM 


MOV 
CALL 


#FC$ 'FNC,F$FNC ( RO ) 
$FDV 


DEFINE  THE  SIZES  OF  THE  ARGUMENT  BLOCKS  FOR  FORM  DRIVER 

.MACRO  $FDVDF 

F$ASIZ  =  16 

F$RSIZ  =  6 
.ENDM 


SCSPON 


This  macro  call  CNSPON  to  put  the  terminal  in  special  mode  and 
lower  case. 


■MACRO    $CSPON 
,ENDM     $CSPON 


;  $CSPOF 


This  macro  calls  CNSPOF  to  put  the  terminal  in  normal  mode  and 
upper  case. 


•MACRO  $CSPOF 
.ENDM  $CSPOF 
.END 


;End  of  FMSMAC.MAC 
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Appendix  B 

FMS  Extended  Examples 


This  appendix  lists  tour  extended  examples  of  F'MS  applications.  The  FMS 
distribution  kit  contains  the  sources  of  these  examples.  They  are  built  auto- 
matically as  part  of  the  FMS-11/RSX  installation  procedure.  You  can  experi- 
ment with  them  while  you  are  learning  to  use  the  F'MS  features. 

Section  B.l  contains  listings  of  an  FMS  application  that  has  been  written  in 
BASIC-PLUS-2,  COBOL- 11,  FORTRAN  IV.  and  MACRO!  1.  All  versions 
of  the  application  use  the  same  form  library  file,  DEMLIB.FLB.  This  file  is 
.:^ls()  in  the  FMS  distribution  kit. 

The  file  names  for  the  extended  examples  as  stored  on  the  FMS  distribution 
kit  are: 


DEMLIB.FLB 

CBLDEM.CBL 

BASDEM.B2S 

FORDEM.FTN 


The     form     library     file     for     BASDEM,     FORDEM, 
CBLDEM  and  MACDEM. 

The  COBOL  version  of  the  program. 

The  BASIC-PLUS-2  version  of  the  program. 

The  FORTRAN  IV  and  FOR  FRAN  IV-PLUS  version  of 
the  program. 


MACDEM. MAC        The  MACRO-U  versi(m  of  the  program. 

For  each  version  of  the  program,  instructions  about  building  a  running  appli- 
cation are  included  as  comments  at  the  beginning  of  the  listing.  Chapter  8, 
"Building  and  Running  FMS  Application  Systems,"  explains  the  building 
procedures  in  detail. 

B.1    A  Typical  Application  Written  in  BASIC-PLUS-2,  COBOL-11, 
FORTRAN  IV,  FORTRAN  IV-PLUS,  and  MACRO-11 

This  secti.m  lists  BASIC  PLUS  2,  COBOL  11,  FORTRAN  IV,  FORTRAN 
I\'  PLCS,  and  MACRO  1 1  versions  of  a  simple  user  program  that  supports  a 
multi-purposf'  data-entry  application.  The  form  library  tile  DEMLIB.FLB 
contains  six  sample  torms  for  the  ap|)lication  and  any  version  ot  the  a|jplica- 
tion  can  use  them.  For  a  tuU  printed  description  of  a  form  in  DEMLIB  FLB, 
you  can  use  the  FMS  Form  I'tility  (FCT).  Chapter '.]  describes  how  to  run  the 
Form  I'tility. 

The  application  supports  different  data-entry  processes  l)y  using  form  de- 
scriptions that  provide  the  details  tor  each  proccs  \  The  program  itselt  shows 


B 


only  the  appropriate  forms,  depending  on  the  process  the  operator  chooses. 
and  collects  the  operator's  responses  to  each  form.  The  application  supports 
the  following  data-entry  processes: 

1.  Create  a  customer  file. 

2.  Create  a  part  description  file. 

3.  Create  an  employee  file. 

4.  Exit. 

As  an  example  of  how  the  application  uses  the  forms,  the  following  sketch 
traces  the  major  processing  steps  in  creating  a  customer  file. 

Starting  the  Process 

Initially,  each  version  of  the  application  displays  a  menu  form  named  'FIRST* 
to  ask  what  process  is  to  he  done.  Figure  B~l  shows  the  form  named  'FIRST' 
with  the  named  data  associated  with  that  form  as  a  circled  insert. 

The  operator  chooses  to  create  a  customer  file  by  typing  '1'  in  response  to  the 
field  prompt  Do  in  the  menu  form. 

The  application  uses  the  operator's  respon.se  to  find  out  the  next  form  to 
display  by  checking  the  named  data  associated  with  the  menu  form.  The 
application  finds  that  the  string  'CUSTO'  corresponds  to  the  operator's  re- 
sponse in  this  case.  The  application  then  creates  a  new  named  data  reference 
('IF')  from  the  operator's  response,  checks  for  it  in  the  menu  form's  named 
data,  and  finds  the  corresponding  string  'SY:NEWCUS.DAT." 


FMS  11  Demonstiatioii  Menu 
Do      • 

1  Create  a  customer  tile 

2  Create  a  part  description  file 

3  Create  an  employee  file 

4  Exit 


Named  Data  Information 


Name 

Data 

1 

CUSTO 

2 

PARTS 

3 

EMPLOY 

IF 

SYNEWCUS 

2F 

SY  PARTS. D 

3F 

SY  EMPLOY 

4 

.EXIT. 

DAT 


DA, 


Not  actually  displayed 


Figure  B-1:    The  Kxtended  Kxample  Form  Named  'FIRST' 
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Collecting  the  Customer  Data 

The  application  continues  processing  by  loading  and  displaying  a  form  in 
DEMLIB.FLB  that  is  named  'CUSTO.'  Figure  B-2  shows  that  form  and  the 
named  data  associated  with  it.  The  application  also  opens  a  customer  data 
output  file  named  NEWCUS.DAT  on  the  system  volume. 


New  Customer  Fotin 

Customei  Njme: 

Address; 

Account  Rep; 

Phone  (617100000000 


'  Not  actually  displayed 


Figure  B-2:    The  Extended  Example  Form  Named  *CUSTO' 


When  the  opf  or  has  completed  the  form  named  'CUSTO,'  the  applicaticm 
writes  the  c  >mer  data  to  the  output  file.  The  application  then  uses  the 
named  data  »  .crence  'NXTFRM'  to  check  for  another  form  that  is  part  of  the 
customer  da^a  process,  hi  the  named  data  associated  with  the  form  named 
'CUSTO;  the  string  TUSTPR'  is  associated  with  'NXTFRM.' 

Completing  the  Customer  Data 

The  application  continues  processing  by  loading  and  displaying  the  form 
named  'CUSTPR.'  Figure  B-3  shows  that  form  and  the  named  data  associ- 
ated with  it.  The  file  NEWCTIS.DAT  remains  open. 

When  the  operator  has  completed  the  form  named  '(T'STPR.'  the  application 
adds  the  responses  to  the  customer  data  output  file  and  checks  the  current 
named  data  for  another  form  name  associated  with  the  reference  'NXJ'FRM.' 
The  application  gets  the  string  '.NONE.' 

Finishing  the  Customer  Data  Entry  Process 

The  application  program  and  forms  have  been  prepared  .so  that  the  program 
gets  the  string  '.NONE.'  alter  the  last  form  in  each  data-entry  process  has 
been  completed.  The  application  then  displays  another  menu  fonn  named 
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CUSTOMER  PROFILE 

Amuial  Income  in  Thousands  SOOOOOO 

Expected  pui chases  SOOOOOO 

Nuinl)ef  (if  eniplovees  000000 


.Vof  actually  displayed 


Figure  B  .{:    7  he  Extended  Example  Form  Named  'CUSTPR' 


LAST."  Figure  H  4  shows  that  form  and  the  named  data  associated  with  it. 
The  lile  NFWCrS.DAT  remains  open  until  the  operator  switches  to  another 
data  entry  process  or  stops  the  appHcation. 

In  the  torm  named  "LAST,"  the  defauh  response  in  the  tieki  header  is  '1/ 
indicating,'  that  the  operator  wants  to  enter  more  customer  data.  The  operator 


[)o        1 


1  Collect  dtldilionjl  ildtd 

2  Return  to  menu 

3  Ex,t 


Not  actually  displayed 


FiKure  HI:    The  Extended  Example  Form  Named  'LAST' 
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can  type  a  dit'i'erent  response  and  either  stoj)  the  a{)pHeati()n  or  return  to  the 
first  menu  torm  ('FIRST")  and  choose  another  data  entry  process. 

Figures  B-fi  and  B-H  show  the  other  iwo  tornis  in  the  form  Hl)rar\-  file 
DEMLIB.FLB  and  the  named  data  associated  with  each  form.  Refer  to  those 
figures  while  you  trace  the  data  entry  processes  for  creating  a  part  descripticm 
file  and  an  employee  file. 


EMPLOYEE  DATA 


EtTi()k)vee  Namr 

Home  addiess; 

\Joik  address 

Plant; 
Loc: 
Mail  stop: 


Ptionc 
Ext 


Not  actually  displayed 


Figure  B-5:    The  Kxtended  Example  Form  Named  'EMPLOY' 


Pait  Numbei 
Description 
Siippliei 
Address 


Salespeison 
Sdi«spotso;i 
Si>lBsperson 


Price  $ 


per 


PART  DESCRIPTION 


' Not  actually  displayed 


Phono (    ' 

Ent 

Phone ( 

EKt 

Phone  1 

Lxt 

Figare  H-(J:    The  Extended  Example  Form  Named  'PARTS' 
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You  can  also  experiment  with  your  own  applications  by  usin^Mhe  P'orm  F^ditor 
to  create  your  own  forms  and  to  add  them  to  DEMLIB.PTB.  II  you  do  that, 
remember  to  modify  the  form  named  'FIRST'  so  that  you  can  access  your  new 
form(s)  from  it. 


• 


B.2    Running  the  Programs 


Before  running  any  of  the  demo  programs,  you  must  have  the  form  library 
DEMLIB.FLB  in  the  system  account  you  are  running  under.  The  demo  pro- 
grams are  built  as  part  of  the  FMS-11/RSX  installation  procedure. 

B.2.1    Running  the  BASIC-PLUS-2  Version 

rvUN  BASDEM.TSK  (RED 


B.2. 2    Running  the  COBOL  Version 


rvUN    CBLDEM.TSK     m 


B.l.w    Running  the  FORTRAN  IV  Version 


ryUN    FORDEM.TSK     m 


B.2.4    Running  the  FORTRAN  IV-PLUS  Version 


RUN    FaPDEM.TSK     ® 


B.2.5    Running  the  iy/IACRO-11  Version 


rvUN    MACDEM.TSh     (Rl?) 
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100 
110 
120 
130 
140 
150 
160 
ilQ 
180 
190 
200 
210 
220 
230 
240 
250 
260 
270 
280 
290 
292 
294 
296 
298 
300 
305 
310 
315 
3" 

33L 
335 
340 
345 
350 
355 
360 
365 
370 
375 
400 
405 
410 
415 
420 
425 
430 
435 
440 
445 
450 
455 
460 
465 
470 
480 
485 
490 


REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
•^EM 
kEM 
^M 
.M 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 
REM 


BASDEM.B2S 


COPYRIGHT  <C>  1981  BY 
DIGITAL  EQUIPMENT  CORPORATION,  MAYNARD ,  MASS, 


MODULE:  BASDEM 

VERSION:  VOl.OO 

AUTHOR:  Megan 

DATE:  lO-APRIL-79 


BASIC  demonstration  program  for  FMS  illustrating  a 
simple  form-driven,  data  entry  application. 

Below  is  an  example  of  a  TKB  command  file  to  build 
this  demonstration  program. 


BASDEM.CMD 

TKB  command  file  to  build  BASDEM 

Underlined  items  are  changes  from  file  built  with 
BASIC+2  BUILD  command. 

SY:BASDEM/CP , BASDEM/-SP=SY : BASDEM/MP 

;  Add  map  file  if  desired. 

UNITS  =  14 
ASG  =  TI:13:5 

;  --  Assign  LUN  5  as  terminal  for 

ASG  =  SY:6:7:8:9: 10 : 11  :  12 

;        -  Remove  LUN  5  from  this  line, 

// 

BASDEM. ODL 

TKB  Overlay  Description  File  for  BASDEM 

Underline!.'  items  are  changes  from  file  built  by 
BASIC+2  BUILD  command. 


FDV, 


USER: 

LIBR: 
FORM: 


ROOT  BASir2-RMSR0T-USER,RMSALL 
FCTR  SY:BASDCM-LIBR-FORM 


.FCTR  LB: (1 ,11BASIC2/LB 
.FCTR  HLLBP2-FRM1 


FRMl 


.FCTR  FDVLRM/l.B 


Add  FMS  factor  to  root 

Add    HLL 
Add    FDV 


(JLB:  [1,11BP2IC1 
CJLB:  [1  ,1]  RMSllS 
.END 
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500 
501 
502 
5L3 
504 
50") 
510 
520 
530 
550 
560 
570 
580 
590 
600 
610 
620 
625 
630 
635 
640 
650 
660 
6  70 
680 
690 
700 
710 
720 
730 
740 
750 
760 
770 
780 
790 
800 
810 
820 
830 
840 
850 
860 
870 
880 
890 
900 
910 
920 
930 
940 
950 


REM  Defined  variables, 

DIM  1^(1500) 

C$=STRING$  (2%, 65%) 

F1$=STRING$  (6%, 32%) 

F2$=STRING!?  (13%, 32%) 

A$=STRING$ (255%, 32%) 

REM  VARIABLE 

REM 

REM  C$ 

REM  S* 

REM  T% 

REM  Fl$ 

REM  F2$ 

REM  F3$ 

REM 

REM  Initialize  Form  Driver  and  open  library, 


DESCRIPTION 


Choice  specified  by  the  user 

FDV  status 

Terminator  code 

The  initial  form  name  of  the  series 

The  outf-iut  file  name 

The  current  form  name 


REM 

CALL  WTQIO(768% , 5% ,5%: 


CALL  FINIT(I% 


1500%) 


Get  the  first  form  name  from 


CALL  FLCHAN(6%)  \  GOSUB  200X1 

CALL  FLOPEN  ("SYrDEMLIB")  \  'gOSUB  2000 

REM 

REM  Show  the  menu  form  for  operator  to  select  the  data 

REM  collection  series, 

REM  named  data. 

REM 

CALL  FCLRSH ("FIRST")  \  GOSUB  2000 

CALL  FGET(C$,T*, "CHOICE")  \  GOSUB  2000 

CALL  FNDATA(C$,F1$)  \  CALL  FSTAT(S%)  \  IF  S%,>0%  GO  TO  770 

CALL  FPUTL("Illegal  choice")  \  GO  TO  710 

REM 

REM  If  form  name  is  ".EXIT.",  terminal  ooerator  is  done. 

REM 

IF  F1S=".EXIT."  GO  TO  12  90 

REM 

REM  Get  the  output  file  name  from  named  data  and  open  it. 

REM 

CALL  FNDATA(TRM$ (C$)+"F" ,F2$) 

OPEN  F2$  FOR  OUTPUT  AS  FILE  #1%,FILESIZE  10% 

REM 

REM  THIS  IS  THE  DATA  COLLECTION  LOOP 

REM 

REM  Set  current  form 

REM 

F3$=F1$ 

REM 

REM  Show  the  form. 

REM 

CALL  FCLRSH (F3$)  \  GOSUB  2000 

REM 

REM  Get  data  for  current  form  and  output  it 

REM 


first  form  in  series 
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960 

970 

980 

990 

1000 

1010 

1020 

1030 

1040 

1050 

1060 

1070 

1080 

1090 

1100 

1110 

1120 

1130 

1140 

1150 

1160 

1170 

1180 

1190 

1200 

1210 

1220 

1230 

1240 

1250 

1260 

1270 

1280 

1290 

2000 

2010 

2020 

2030 

2040 

2050 

2060 

2070 

9999 


End  of  the 
we ' re  done 


If  found,  loop  for  more  data 


form  seiies.  Show  LAST  to  determine  if 
or  not . 


CALL  FGETAL(A$)  \  GOSUB  2000 

PRINT  #1%,TRM$(A$) 

REM 

REM  Get  name  of  next  form. 

REM 

CALL  FNDATAC'NXTFRM"  ,F3$) 

IF  F3$<>".N0NE."  GO  TO  920 

REM 

REM 

REM 

REM 

CALL 

CALL 

REM 

REM  If  response  =  "1",  repeat  data  collection  loop 

REM 

IF  C$="l"  GO  TO  880 

REM 

REM  Get  named  data  corresponding  to  response. 

REM  Get  field  again  if  illegal  response. 

REM  Close  output  file  for  valid  response 

REM 

CALL  FNDATA(C$,F3$)  \  CALL  FSTAT(S%)  \  IF  S%>0% 


FCLRSH  ("LAST")  \  GOSUB  200C 
FGET(C$,T%, "CHOICE")  \  GOSUB  2000 


other  than  1 


GO  TO  1200 


choice")  \  GO  TO  1080 


'  .EXIT, 
again , 

700 
and 


terminal  operator  is  done,  else 


CALL  FPUTL("Illegal 

CLOSE  #1% 

REM 

REM  If  named  data  is  ' 

REM  display  menu  form 

REM 

IF  F3$<>" .EXIT. "  GO  TO 

REM  Close  form  library  and  exit 

REM 

REM 

CALL  FLCLOS  \  GO  TO  9999 

REM 

REM  Output  message  and  exit  if  I/O  error  returned  from 

REM  Form  Driver.  This  is  the  only  error  expected  in  a 

REM  debugged  application. 

REM 

CALL  FSTAT(S%) 

IF  S%>0%  THEN  RETURN 

CALL  FPUTL{"Fatal  I/O  Error")  \  STOP 

END 
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COBDEM.CBL 

COPYRIGHT  (C)  1981  BY 
DIGITAL  EQUIPMENT  CORPORATION,  MAYNARD,  MASS. 


MODULE: 
VERSION; 
AUTHOR: 
DATE: 


COBDEM 

vol. 00 

MEGAN 
21-FEBRUARY-80 


COBOL  demonstration  program  for  FMS  illustrating  a 
simple  form-driven,  data  entry  application. 

The  following  is  a  brief  description  on  compiling  and 
building  COBDEM. 

The  command  to  compile  the  program  is: 

CBL  COBDEM, COBDEM=COBDEM/ERR: 1 

where:   /ERR:1  suppresses  diagnostic  error  logging 

Below  is  an  example  of  a  TKB  command  file  to  build 
this  demonstration  program. 


COBDEM.CMD 

TKB  command  file  to  build  COBDEM 
COBDEM ,COBDEM/-SP=COBDEM 

;  COBOL  interface  and  Form  Driver  library 

HLLCOB,FDVLRM/LB 


LB: [1 ,11C0BLIB/LB,RMSL IB/LB 

/ 

UNITS=9 

;       LUN  1  will  be  the  terminal. 

ASG  =  TI:1 

}       LUN  3  will  be  the  output  file  unit. 

ASG  =  SY: 3 

;        Reassign  the  logical  unit  in  the  Form  Driver. 

GBLDEF  =  T$LUN:1 

// 

IDENTIFICATION  DIVISION. 
PROGRAM-ID.     COBDEM. 
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* 
* 
* 
* 
* 
* 


TEST  PROGRAM 


ENVIRONMENT  DIVISION. 

CONFIGURATION  SECTION. 

INPUT-OUTPUT  SECTION. 

FILE-CONTROL. 

SELECT  OUTPUT-FILE  ASSIGN 

DATA  DIVISION. 

FILE  SECTION. 


TO  "SY; 


* 

* 
FD 


Create  a  sequential  file  for  c  itput  of  form  data 

OUTPUT-FILE 

LABEL  RECORDS  ARE  STA.>JDARD 
VALUE  OF  ID  IS  ANSWER2. 
POOL  PIC  X(256) . 


Data  f ol lows 


01 

* 
* 
* 

WORKING-STORAGE  SECTION. 
*       System  form  library. 

DEMLIB        PIC  X(10)  VALUE 


01 

* 


Loqical  unit  number  for 


01 

* 

01 

* 

0' 
01 

01 

* 

* 


LUN 


"DEMLIB. FLB ■ . 
attaching  the 


term  inal 


PIC  9(9) 
Impure  area. 


COMP  VALUE  J 


IMPURE        PIC  X(2000)  . 
Size  of  impure  area. 
ISIZE         PIC  9(9)  COMP  VALUE  2000 
INUM  PIC  999  COMP  VALUE  768. 

UN  PIC  9  COMP  VALUE  1. 


Special  work  area. 

ANSWERl  ->  The  initial  form  name  of  the  series, 

ANSWER2  ->  The  output  file  name. 


ANSWER3  ->  The  current  for 


m  name, 


01  ANSWERl. 

02  PART  PIC  X(6)  . 

02  FILLER  PIC  X(7) . 
01  ANSWER2       PIC  X(1J; 
01  ANSWER3. 

02  PART  PIC  X(6)  . 

02  FILLER  PIC  X(7)  . 


Fieldf  used  to  create  a  field 


name 


01  FIELDF. 

02  DAT  PIC  X. 

02  FILLER  PIC  X(5)  VALUE  "F 


01  FIELD 


PIC  X(b) 
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status 


01  STAT  PIC  9(9)  COMP. 

01  STAT2         PIC  9(9)  COMP. 

* 

*       Error  message  on  program  errors, 


01  ERRl. 
02  PARTI 
02  ERR-STAT 
02  PART2 


PIC  X(22)  VALUE  "FATAL  I/O  ERROR,  STAT^ 

PIC  ZZ9-  DISPLAY. 

PIC  X(8)  VALUE  ",  STAT2=". 


02  ERR-STAT2   PIC  ZZ9-  DISPLAY 


02  PART3 
01  ILL-CHOICE 


PIC  X(l)  VALUE  "  "  . 

PIC  X(14)  VALUE  "ILLEGAL  CHOICE". 


FORM  DESCRIPTION  STARTS  HERE 


* 

* 

COPY  "DEMLIB.LIB 
* 


PROCEDURE  DIVISION. 
MAIN-CONTROL  SECTION. 
PI. 

*  Attach  the  terminal. 
CALL  "WTQIO"  USING  INUM,UN,UN. 

*  Initialize  and  open  the  library. 
CALL  "FINIT"  USING  BY  DESCRIPTOR  IMPURE, 

BY  REFERENCE  ISIZE. 
CALL  "FLCHAN"  USING  LUN . 
PERFORM  STATUS-CHECK. 

CALL  "FLOPEN"  USING  BY  DESCRIPTOR  DEMLIB, 
PERFORM  STATUS-CHECK. 

Display  first  form. 


P6 


CALL  "FCLRSH"  USING  BY  DESCRIPTOR  FORM-FIRST. 
PERFORM  STATUS-CHECK. 


* 
P2 


Show  the  menu  form  for  operator  to  select  the  data 
collection  series.   Get  the  first  form  name  from 
named  data. 

CALL  "FGET"  USING  BY  DESCRIPTOR  D-FIRST-CHOICE , 

BY  REFERENCE  STAT, 
B"  DESCRIPTOR  N-FI RST-CHOICE . 
PERFORM  STATUS-CHECK. 
MOVE  D-FIRST-CHOICE  TO  FIELD. 
MOVE  SPACES  TO  ANSWERl . 
CALL  "FNDATA"  USING  BY  DESCRIPTOR 

FIELD, ANSWERl. 
CALL  "FSTAT"  USING  STAT. 
IF  S.AT  NOT  >  0 

CALL  "FPUTL"  USING  BY  DESCRIPTOR  ILL-CHOICC 

PERFORM  STATUS-CHECK 

CC  TO  P2 . 
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* 

* 
* 


* 
* 
* 

P4 

* 
P3 


* 
* 
* 


* 
* 
* 
* 


P5 


* 
* 
* 

* 
* 
* 
* 
* 


If  form  name  is  ".EXIT.",  terminal  operator  is  done. 

IF  PAKT  OF  ANSWERl  =  ".EXIT."  GO  TO  LIB-CLOSE. 

Get  the  output  file  name  from  named  data  and  open  it 

MOVE  D-FIRST-CHOICE  TO  DAT  OF  FIELDF. 

MOVE  SPACES  TO  ANSWER2 . 

CALL  "FNDATA"  USING  BY  DESCRIPTOR 

FIELDF, ANSWER2. 
PERFORM  STATUS-CHECK. 
OPEN  OUTPUT  OUTPUT-FILE. 

This  is  the  data  collection  loop. 


MOVE  ANSWERl  TO  ANSWER3. 
Show  the  form. 

CALL  "FCLRSH"  USING  BY  DESCRIPTOR  ANSWER3. 
PERFORM  STATUS-CHECK. 


Get  data  for  current  form  and  output  it. 

MOVE  SPACES  TO  POOL. 

CALL  "FGETAL"  USING  BY  DESCRIPTOR  POOL. 

PERFORM  STATUS-CHECK. 

WRITE  POOL. 

Get  name  of  next  form.   If  found,  loop  for  more  data 

MOVE  "NXTFRM"  TO  FIELD. 

CALL  "FNDATA"  USING  BY  DESCRIPTOR 

FIELD, ANSWER3. 

PERFORM  STATUS-CHECK. 

IF  PART  OF  ANSWER3  NOT  =  ".NONE."  GO  TO  P3. 

End  of  the  form  series.   Show  last  to  determine  if 
we ' re  done  or  not . 

CALL  "FCLRSH"  USING  BY  DESCRIPTOR  FORM-LAST. 
PERFORM  STATUS-CHECK. 


CALL  "FGET"  USING  BY  DESCRIPTOR  D-LAST-CHOICE , 

BY  REFERENCE  STAT, 
BY  DESCRIPTOR  N-LAST-CHOICE . 

PERFORM  STATUS-CHECK. 

MOVE  D-LAST-CHOICE  TO  FIELD. 

If  response  =  "1",  repeat  data  collection  loop. 
IF  FIELD  =  "1"  GO  TO  P4 . 

Get  named  data  corresponding  to  response. 

Get  field  again  if  illegal  response. 

Close  output  file  for  valid  response  other  than  1 

CALL  "FNDATA"  USING  BY  DESCRIPTOR  FI ELD  ,  ANSWER3 . 
CALL  "FSTAT"  USING  STAT. 
IF  STAT  NOT  >  0 

CALL  "FPUTL"  USING  BY  DESCRIPTOR  ILL-CHOICE 

PERFORM  STATUS-CHECK 

GO  TO  P5. 
CLOSE  OUTPUT-FILE. 
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If  named  data  is  ".EXIT.",  terminal  operator 
is  done,  else  display  menu  form  again. 

IF  PART  OF  ANSWER3  NOT  =  ".EXIT."  GO  TO  P6 . 

Close  form  library  and  exit. 


LIB-CLOSE. 

CALL  "FLCLOS". 
PERFORM  STATUS-CHECK 
STOP  RUN. 


Output  message  and  exit  if  I.O  error  returned  from 
Form  Driver.  This  is  the  only  error  expected  in  a 
debugged  application. 


STATUS-CHECK  SECTION. 
SCI. 

CALL  "FSTAT"  USING  STAT,STAT2. 

IF  STAT  >  0  GO  TO  SC2. 

MOVE  STAT  TO  ERR-STAT. 

MOVE  STAT2  TO  ERR-STAT2 . 

CALL  "FPUTL"  USING  BY  DESCRIPTOR  ERRl 

STOP  RUN. 


SC2 


EXIT. 
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c 
c 
c 
c 
c 
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c 
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c 
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c 
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c 


FORDEM.FTN 


COPYRIGHT  (C)  I'r^Sl  BY 
DIGITAL  EQUIPMENT  CORPORATION,  MAYNARD ,  MASS, 


MODULE: 
VERSION: 
AUTHOR: 
DATE: 


FORDEM 

vol  .00 

Megan 

l-APRIL-79 


FORTRAN  demonstraf- ion  program  for  FMS  illustrating  a 
simple  form-drive    data  entry  application. 

This  module  is  compiled  as  follows: 

FOR  FORDEM, FORDEM=FORDEM  { F4 ) 

or 

F4P  F4PDEM,F4PDEM=FORDEM         (F4+) 

The  tasks  are  built  as  shown  below: 


;        Build  the  demo  for  FORTRAN  IV 

I 

FORDEM , FORDEM/CR/-SP=FORDEM 

;  FORTRAN  interface  and  Form  Driver  library  next 
HLLFOR,FDVLIB/LB 
11,11 FOROTS/LB 
// 


Build  the  demo  for  FORTRAN  IV+  with  FCS  support 

■4PDEM/FP,F4PDCM/CR/-SP=F4PDEM 

FORTRAN  interface  and  Form  Driver  library  next 
HLLFOR,FDVLIB/LB 

FORTRAN  IV+  OTS  with  FCS  support 
(1,11  F4l'0TS/LB 
// 


..^  ut-mo  for  FORTRAN  IV+  with  RMS  support 

with  RMS)  next 


F4PDEM/FP,F4PDEM/CR/-SP=F4PDEM 

;  FORTRAN  interface  and  Form  Driver  library 

HLLFOR,FDVLRM/LB 

;  FORTRAN  IV+  OTS  with  RMS  support 

11,1] F4P0TS/LB 

// 
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IMPLICIT  INTEGER  (A-Z) 

DIMENSION  IMPURE  (1000) 

BYTE  RESP(3),  F0RM(7),  F0RMl(7),  DNAM(3),  FILE(30),  DATA{255 
C 

C  Initialize  impure  area  for  Form  Driver  and  open  form  library. 
C 

CALL  WTQIO  (768,5,5)  'ATTACH  THE  TERMINAL 

CALL  FINIT  (IMPURE,  1000) 

CHAN=2 

CALL  FLCHAN(CHAN) 

CALL  ERROR  (FLOPEN  ('DEMLIB')) 
C 

C  Display  menu  form. 
C 

10       CALL  ERROR  (FCLRSH  ("FIRST  ')) 
C 

C  Get  input  from  terminal.  Get  named  data  (name  of  first  form  in 
C  series  or  .EXIT.)  corresponding  to  user's  choice.  If  named  data 
C  doesn't  exist,  input  invalid. 
C 
20       CALL  ERROR  (FGET  (RESP,  TERM,  'CHOICE')) 

IF  (FNDATA  (RESP,  FORMl )   .GT.  0)  GOTO  30 

CALL  FPUTL  ('Illegal  choice') 

GOTO  20 
C 

C  Chock  for  exit.  If  choice  not  exit,  get  name  of  corresponding 
C  file  and  open  it  for  output. 
C 
30       IF  (SCOMP  (FORMl,  '.EXIT.')  .NE.  0)  GOTO  40 

CALL  FLCLOS       !  CLOSE  FORM  LIBRARY 

STOP 
40       CALL  CONCAT  (RESP,  'F',  DNAM) 

CALL  FNDATA  (DNAM,  FILE) 

OPEN  (NAME  =  FILE,UNIT=1 ,  I  N ITI ALS I Z E  =  1 0 ) 
C 

C  Display  form  and  collect  data;  write  data  to  output  file. 
C 
50       CALL  SCOPY  (FORMl,  FORM,  6) 
60       CALL  ERROR  (FCLRSH  (FORM)) 

CALL  ERROR  '  FGETAL  (DATA)) 

WRITE  (1,70)   (DATA(I),  I  =  1 , LEN  (  DATA )  ) 
70       FORMAT  (78A1)  ! DATA  IS  BROKEN  INTO  SEGMENTS  FOR  OUTPUT 


C  Get  name  of  next  form  in  series.  Check  for  none. 
C 

CALL  FNr\TA  ('NXTFRM',  FORM) 

IF  (SCOMP  (FORM,  '.NONE.')  .NE.  0)  GOTO  60 
C 

C  If  last  form  in  series  done,  display  a  menu  form. 
C  Get  input  from  terminal.  Get  named  data  corresponding 
C  to  user's  choice.  If  no  named  data,  invalid  input. 
C 

CALL  ERROR  (FCLRSH  ('LAST')) 
80       CALL  ERROR  (FGET  (RESP,  TERM,  'CHOICE')) 

IF  (FNDATA  (RESP,  FORM)  . GT .  0)  GOTO  ^0 

CALL  FPUTL  ('Illegal  choice') 

GOTO  60 
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C  If  choice  =  1 


,  repeat  series 


C  Else  close  output  file;  check  for  exit  or  go  back  to 
C  initial  menu  form. 


C 


yo 


IF  (RESP(L)  .EQ 
CLOSE  (UNIT=1) 
IF  (SCOMP(FORM, 
CALL  FLCLOS 
STOP 
END 


1')  GOTO  5U 

.EXIT.')   .NE.  0)  GOTO 
CLOSE  FORM  LIBRARY 


10 


SUBROUTINE  ERROR  (RESULT) 
C 

C  Output  message  and  exit  if  I/O  error  returned  from 
C  Form  Driver.  This  is  the  only  error  expected  in  a 
C  debugged  application. 
C 

IMPLICIT  INTEGER  (A-Z) 


IF  {RESULT  .GT.  0)  RETURN 
CALL  FPUTL  ('Fatal  I/O  Error') 
STOP 
END 


SUBROUTINE  SCOPY  (SRC,  DST,  LEN) 
C 

C  Copy  a  string  of  a  specified  length 
C 

C  SRC  =  source  byte  string 

C  DST  =  destination  byte  string  to  be  ended  by  a  zero 
C  LEN  =  number  of  characters  to  copy 
C 

BYTE  SRC  (  1)  ,  DST(l) 

INTEGER  LEN 
C 

C  Copy  source  to  destination  for  length 
C 

DO  10  I  =  1 ,  LEN 

DST(I)  =  SRC  (I) 
10        CONTINUE 
C 
C  End  destination  string  with  zero  byte 


DST(LEN+1)  =  0 

RETURN 

END 


• 
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INTEGER  FUNCTION  SCOMP  (SRCl,  SRC2) 
C 

C  Compare  two  strings 
C 

C  SRCl  =  first  comparand  byte  string  ended  by  a  zero 
C  SRC2  =  second  comparand  byte  string  ended  by  a  zero 
C 

C  Value  of  function  is  zero  for  equal,  nonzero  for  not  equal 
C  Compare  returns  failure  if  string  lengths  are  not  the  same 
C 

BYTE  SRCl (1)  ,  SRC2(1) 
C 

C  Compare  until  either  string  ends  in  zero  byte  or  does  not  match 
C 

I  =  1 
10        IF  (SRCl(I)  .EQ.  0  .AND.  SRC2(I)  . EQ .  0)  GOTO  20 

IF  (SRCl(I)  .NE.  SRC2(I))  GOTO  30 

1  =  1  +  1 

GOTO  10 


C  Return  success 
C 

20       SCOMP  =  0 
RETURN 


C  Return  failure 

C 

30       SCOMP  =  1 

RETURN 
C 

END 

c 

SUBROUTINE  CONCAT  (ST^l,  SRC2 ,  DST) 
C 

C  Concatenate  two  string  into  a  third 
C 

C  SRCl  =  first  source  string  ended  by  a  zero 
C  SRC2  =  second  source  string  ended  by  a  zero 
C  DST  =  destination  string  ended  by  a  zero 
C 

BYTE  SRCl(l),  SRC2(1),  DST ( 1 ) 
C 

C  Copy  the  first  string  into  destination 
C 

J  =  1 

I  =  1 
10        IF  (SRCl'')  .EQ.  0)  GOTO  20 

DST(J)  =  SRCl (I ) 

J  =  J  +  1 

1  =  1  +  1 

GOTO  10 


C  Now  for  second  string  to  destination 

C 

20       1  =  1 

30        DST(J)  =  SRC2(I) 

IF  (SRC2{I)  .EQ,.  0)  GOTO  40 

J  =  J  +  1 

1  =  1  +  1 

GOTO  JO 
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C  Return 

C 

4U        RETURN 

END 
C 

SUBROUTINE  INSERT  (SRC,  DST ,  POS) 
C 

C  Replace  a  portion  of  one  string  with  another 
C 

C  SRC  =  source  string  ended  by  a  zero 
C  DST  =  destination  string  ended  by  a  zero 

C  POS  =  position  ir,  destination  for  scree  string  contents 
C 

BYTE  SRC(l) ,  DST(l) 

INTEGER  POS 
C 

C  Scan  the  destination  string  for  its  end 
C 

J  =  1 
10        IF  (DST(J)  .EQ.  0)  GOTO  20 

J  =  J  +  1 

GOTO  10 
C 

C  Copy  source  into  destination  at  position  given 
C 

20        1  =  1 
30        IF  (SRC(I)  .EQ.  0)  GOTO  40 

DST(I+P0S-1)  =  SRC(I) 

1  =  1  +  1 

GOTO  3  0 
C 

C  End  destination  string  if  source  extends  it  and  return 
C 
40        IF  (I  .GT.  J)  DST(J)  =  0, 

RETURN 

END 


INTEGER  FUNCTION  INDEX  (SRC,  STR) 
C 
C  Find  position  of  one  string  in  another 


C  SRC  =  source  string 

C  STR  =  target  string 

C 

C  Value  of  function  is  zero  if  not  found, 

C  or  position  of  first  character  of  STR  in  SRC  if  found 


BYTE  SRC(l)  ,  STR(l) 
C 
C  Look  for  STR  in  SRC  until  end  of  SRC 


10 


J  =  0 

J  =  J  +  1 

I  =  0 

IF  (SRC(J)  .EQ.  0)  GOTO  30 


FMS  Kxti'Mded  Kxumples    B-19 


c 

C  If  end  of  STR  then  success 

C  If  not  match  look  at  next  position  in  SRC 

C 

20        IF  (STR(I+1)  .EQ.  0)  GOTO  40 

IF  (SRC(J+I)   .NE,  STR(I+1))  GOTO  10 

1  =  1  +  1 

GOTO  20 
C 

C  Retur  n  failure 
C 
30        INDEX  =  0 

RETURN 
C 

C  Return  success,  position  of  string 
C 
40        INDEX  =  J 

RETURN 
C 

END 
C 

INTEGER  FUNCTION  LEN  (STR) 
C 

C  Return  length  of  string  ended  by  a  zero 
C 

C  STR  =  String  ended  by  a  zero 
C 

C  Value  of  the  function  is  the  i.er.gth  of  the  string  without  the  zero 
C 

BYTE  STR(l) 
C 

C  Scan  for  the  zero  byte 
C 

I  =  1 
10        IF  (STR(I)  .EQ.  0)  GOTO  20 

1  =  1  +  1 

GOTO  10 
C 

C  Return  the  length  of  the  string 
C 
20        LEN  =1-1 

RETURN 

END 
C 
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.TITLE   MACDEM   -  FMS  DEMONSTRATION  SUBROUTINE 


MACDEM.MAC 


MODULE: 
VERSION; 
AUTHOR: 
DATE: 


COPYRIGHT  (C)  1981  BY 
DIGITAL  EQUIPMENT  CORPORATION,  MAYNARD ,  MASS 


MACDEM 

vol  .00 

MEGAN 
L9-NOVEMBER-79 


ENABL   LC 


;  Allow  loworcasi  source  text 


.MCALL  $FDV,$FDVDF 

.MCALL  QIOW$S,EXIT$S 

,MC''\LL  FINIT:?  ,FSRSZ$ 

.MCALL  FDBDF$ , FDRC$ A , FDOP$A , NMBLKS 

.MCALL  FDAT$A,0PEN$W, PUT$ , CLOSED 


Identify  Form  Driver  macro  calls 
RSX  I/O  related  macros 
PCS  macros 


FSRSZ.>   1 
SFDVDF 


;  Set  the  file  storage  region 

;  Init  ttic  Forn-  Driver  definitions 


Eauated  symbols 


ISIZ  =  U)24 

INSCHN=1 

0U$CHN=2 


f;:xtnam 
nonnam 

FSTNAM 

LSTNAM 

CHCNAM 

NXTNAM 

LIBNAM 

MSGl  : 

MSG2  : 


SBTTL   Local  data 


,ASCI 
,ASCI 
,  ASCI 
,ASCI 
,ASCI 
,ASCI 
.ASCI 
,  ASCI 
,ASCI 
.EVEN 


/ .EXIT./ 
/.NONE./ 
/FIRST  / 
. LAST  / 
/CHOICE/ 
/NXTFRM/ 
/DEMLIB/ 
/Illegal 


choice/ 


*Fatal  I /O  error* 


Size  of  FDV  impure  area 

Input  channel  number  (Form  Library) 

Outf)ut  channel  number  (Output  File) 


Exit  name 

No  more  forms  in 

ASCI  I  form  name 

ASCII  form  name 

ASCII  field  name 

ASCII  named  data 

ASCIZ  library  name 

Message  for  illegal  menu  choice 

Message  with  embedded  '/' 


ser  les 


field  name 
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Argument  lists  and  data  area 


ARGLST; 
REQLST; 

STAT: 

VARl  : 


BLKB 
BLKB 

BLKW 

BLKB 


F$ASIZ 
F$RSIZ 


OUTFIL 

.BLKW 

5 

FRMNAM 

.  BLKW 

3 

SAVNAM 

.BLKW 

3 

FILBLK 

.  BLKW 

1 

BUFADR 

.BLKW 

1 

BUFFER 

.BLKW 

256. 

ENDBUF= 

=  . 

FILNAM 

.  BLKB 

20 

IMPURE 

.WORD 

ISIZ 

.BLKB 

ISIZ-2 

Form  Driver  argument  list 
Form  Driver  required  list 

Form  Driver  status  block 

Variable  6-byte  block  for  qoneral  use 

Output  file  name 
Area  for  form  names 
Save  area  for  a  form  name 
Length  of  file  in  blocks 
Length  of  data  in  buffer 
Length  of  output  buffer 

16  bytes  for  ASCII  file  name 
Form  Driver  impure  area 


I/O  section 


OUTFDB:   FDBDF$ 

FDAT$A  R.VAR,FD.CR 

FDRC$A  , BUFFER 

FDOPSA  OU$CHN ,DSDS.NMBLK 


NMBLK: 

NMBLKS 

,DA 

DSDS: 

.WORD 

0,0 

.WORD 

0,0 

.WORD 

0,0 

Define  the  FDB 

Variable-length  records  with  CR/LF 
Allow  read,  write  and  modify 
File  doscr  iptor s 

Default  for  file 

Default  the  device  name 

and  file  directory 
This  is  the  file  name  length 

and  file  name 


.EVEN 

.SBTTL   MACDEM   -  FMS  Demonstration  Subroutine 


FUNCTIONAL  DESCRIPTION: 

This  is  the  MACRO  demonstration  program  for  FMS 
illustrating  a  simple  form-driven,  data  '-ntry 
appl icat  ion . 


DEMO; 


.PSECT  MACDEM 

FINIT:? 

QIOW$S  #I0.ATT,#T$LUN,#T$EFN 

BCC  1$ 

CALL  LEAVE 


Initialize  for  FCS  I/O 

Attach  the  terminal 

If  error  then  ]ust  leave 

Done  for  now 
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1? 


MOV 


#ARGLST,RO 


RO  =  addr  of  FDV  arg  list 


FIRST; 


1U$ 


20$ 


3U$ 


6U$ 


MOV  #REQLST,R1 

MOV  #STAT,F$STS  (Rl ) 

MOV  #IN$CHN,F$CHN (Rl) 

MOV  #IMPURE,F$IMP(R1) 

$FDV  REQ=R1 

$FDV  FNC=OPN,NAM=#LIBNAM 

CALL  ERREX 

$FDV  FNC=CSH,NAM=#FSTNAM 

CALL  ERREX 

$FDV  FNC=GET,NAM=#CHCNAM 

CALL  ERREX 

MOV  #VAR1,R1 

CALL  BLKNAM 

MOVB  vJF$VAL(RG)  ,VARl 

$FDV  FNC=DAT,NAM=#VAR1 

TST  STAT 

BGT  20$ 

$FDV  FNC  =  LST,VAL  =  #MSG1  ,LEN=ff- 

BR  10$ 

MOV  F$VAL(RO) ,Rl 

MOV  #EXTNAM,R2 

CALL  CMPNAM 

BNE  iO$ 

JMP  LIBCLS 

CALL  MOVNAM 

MOV  #FRMNAM,R1 

MOV  #SAVNAM,R2 

.REPT  3 

MOV   (Rl)  +  ,  (P2)  + 
.ENDR 

CLR  FILBLK 

MOV  tfBUFFER,BUFADR 

MOVB  #'F,VAR1+1 

MOV  »VAR1,RI 

$FDV  FNC=DAT,NAM=R1 

CALL  DATSET 

OPEN$W  »OUTFDB 

BCC  60$ 

CALL  LEAVE 

$FDV  ARG=#ARGLST,FNC=CSH,NAM= 

CALL  ERREX 

$FDV  FNC=ALL 

CALL  ERREX 

CALL  SAVDAT 

$FDV  ARG=#ARGLST,FNC=DAT,NAM= 


Rl  =  addr  of  FDV  required  arg  list 
Set  addr  of  status  block 
Set  I/O  channel  for  FDV 
Set  addr  of  FDV  impure  area 

Init  required  arg  list  pointer 
Open  form  library 
Exit  with  error 

Show  menu  form 
Exit  if  error 

Get  field  'CHOICE' 
Exit  if  error 

Rl  =  ptr  to  6-bytG  block 

Blank  out  VARl 

VARl  =  menu  choice 

Get  named  data  with  the  name  being 
the  response  to  'CHOICE' 

v;as  get  successful? 

Continue  if  ok 
1  ;  Else  print  message  on  line  24 
;  Try  again 

Rl  =  addr  of  name  from  named  data 

R2  =  addr  of  exit  name 

Zero  sot  on  match 

Continue  on  match 

Else  close  form  library  and  exit 

Save  named  data 

Rl  =  adr  of  source  name 

Adr  to  save  form  name 

Save  form  name 

Init  file  length 

Init  buffer  adr 

Make  2nd  letter  =  F 

Rl  =  addr  of  6-byte  block 

Get  named  data  at  VARl 


;  Go  set  up  a  data  set  descriptor 

;  Open  the  file 

;  Continue  if  ok 

;  Leave  on  I/O  error 

^#FRMNAM 
;    Exit    witli    error 

;  Get  all  data  from  form 
;  Exit  with  error 

;  Put  data  in  file 

#NXTNAM  ;  Got  name  of  next  form 


I 
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CALL 

MOVNAM 

MOV 

#NONNAM,Rl 

MOV 

#FRMNAM,R2 

CALL 

CMPNAM 

bl:q 

70$ 

BR 

60$ 

70$: 

$FDV 

FNC  =  CSH,NAM=tfLSTNAM 

CALL 

ERREX 

H0$: 

$FDV 

FNC-GET,NAM=#CHCNAM 

CALL 

ERREX 

MOV 

F$VAL (RO) ,RJ 

CMPB 

(Rl)  ,#'1 

BNE 

90$ 

MOV 

#SAVNAM,Rl 

MOV 

#FRMNAM,R2 

.RLPT 

3 

MOV 

(Rl)+, (R2)+ 

.ENDR 

BR 

60$ 

90$: 

MOVB 

(Rl) ,VARl 

MOVB 

#40  ,VAR1  1-1 

$FUV 

FNC=DAT,NAM=#VAR1 

TST 

STAT 

3GT 

CHKCLS 

$FDV 

FNC=LST, VAL=#MSG1 ,LEN=# 

BR 

80$ 

Put  form  name  in  FRMNAM 

Rl  =  adr  of  ASCII  .NONE. 

R2  =  adr  of  returned  name 

Zero  set  on  match 

Display  last  form  on  match 

Else  qct  data  from  next  form 


;  Exit  with  error 


Exit  with  e'ror 

Rl  =    adr  of  answer 
Is  It  =  1 

i'i  =  source  name 
r2  =  dost  name 

Move  nam.e 

Get  more  data 

Move  into  variable  for  name 

Make  2nd  char  blank 

Get  named  data 

Check  status 

If  ok  then  close  file 

--1  ;  Print  message  on  line  24 
;  Try  again 


Close  the  output  file 


CHKCr.S: 

CLOSE$ 

#OUTFDB 

MOV 

ffFXTNAM,Rl 

MOV 

!fARGLST,RO 

MOV 

FSVAL(RO)  ,R2 

CALL 

CMPNAM 

BEQ 

LIBCLS 

J  MP 

FIRST 

LIBCLS: 

$FDV 

FNC=CLS 

BR 

EXIT 

Close  output  file 

Name  of  exit  named  data 

Get  ARGLST 

R2  =  adr  of  named  ..ata 

Zero  set  i  f  match 

Exit  on  match 

Back  to  start  on  no  match 

Close  form  Jibrary 

And  exit 


Routine  to  chock  for  error  return  from  Form  Driver 
Print  message  and  exit  on  error. 


ERREX: 

TST 

STAT 

BLP 

LEAVE 

RETURN 

LEAVE: 

$FDV 

ARG  =  i» 

$FDV 

FNC  =  L 

EXIT: 

EXIT$S 

;  Was  call  ok? 


FNC=LST,VAL=#MSG2 ,LEN=#~1     ;     Print    message    on    line    24 
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;  Subroutine  to 

store  data  in  output  file 

SAVDAT: 

MOV 

F$VAL  (RO)  ,R2              ; 

MOV 

F$LEN (RO) ,R3              ; 

TST 

R3 

BLE 

10$ 

PUT$ 

#0UTFDB,R2,Ri             ; 

10$: 

RETURN 

R2  =  adr  of  data  returned 

R3  =  length  of  data  returned 

Was  data  returned? 

I  f  not  return 

Store  away  the  string  of  data 


Subroutine  to  move  name  and  blank  fill  to  6  chars 
F$VAL(RO)  =  Addr  of  source  name 
F$LEN{r0)  =  Length  of  source  name 
FRMNAM  =  Addr  of  destination  of  name 


MOVNAM: 

MOV 

# FRMNAM, Rl 

CALL 

BLKNAM 

MOV 

F$VAL (RO) ,Rl 

MOV 

#FRMNAM,R2 

MOV 

F$LEN(RO) ,R3 

10$: 

MOVB 

(Rl)  +  ,  (R2)  + 

DEC 

RJ 

BNE 

10$ 

RETURN 

Rl  =  addr  to  store  form  name 

Blank  out  name 

Rl  =  addr  of  named  data 

R2  =  addr  to  store  form  name 

Length  of  named  data 

Move  named  data  to  form  name 

Dec  char  ctr 


Subroutine  to  blank  6  bytes 

Rl  =  Addr  of  name  to  blank 


BLKNAM: 

MOV 

»6,R2 

5$: 

MOVB 

#4U, (Rl)+ 

DEC 

R2 

BNE 

5$ 

RETURN 

R2  =  6 

I  nit  name  with  blanks 

Dec  byte  ctr 


Subroutine  to  compare  two  b-byte  names 
R1,R2  point  to  names 
R3  =  0  if  match  on  return 


CMPNA.l: 

MOV 

#6,R3 

10$: 

CMPB 

(Rl)  +  ,  (R2)  + 

BNE 

20$ 

DEC 

R3 

BNE 

10$ 

2U$: 

RETURN 

6  char  compare 
Compare  2  bytes 
Leave  loop  if  no  match 
Dec  char  ctr 
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WE  ARE  GOING  TO  B"ILD  THE  DATASET  DESCRIPTOR  BY  HAND 


DATSET: 


30$: 
40$: 


50$ 
60$ 


70$ 


MOV 

MOV 

.REPT 

CLR 

.ENDM 

MOV 

MOV 

MOV 

TST 

BEQ 

CMPB 

BEQ 

DEC 

CMPB 

BNE 

DEC 

ASR 

ASR 

INC 

ASL 

ASL 

ADD 

MOV 

SUB 

MOV 

TST 

BEQ 

BR 

RETURN 

.END 


F$LEN+ARGLST,R4 

ffDSDS,R3 

6 

(Ri}  + 

F$VAL+ARGLST,R1 
Rl  ,R2 
#2,R3 
R4 
60$ 

(Rl)  ,#'  1 
5  0$ 
R4 

(Rl)  +  ,#•  : 
40$ 
Rl 
R3 
R3 
Rl 
R3 
R3 

#DSDS,R3 
Rl, (R3) 
R3)  + 


R2, 

R2, 

R4 

70$ 

30$ 


;jEMO 


R3) 


Set  St  r  inq  si  ze  in  R4 

Clear  the  dataset  descriptor 

So  we  don't  imply  any  defaults 


->  f 

Save 

Assu 

End 

Yes 

Dire 

Yes 

Deer 

Dev  i 

Nope 

Back 

Ad  j  u 

Ad  j  u 

Ad  j  u 

Ad  j  u 

Into 

Make 

Make 

As  e 

Save 

See 

Yes 

Nope 

Retu 


ilespec 
->  start  of  substring 
me  its  a  filename  (offset/4) 
of  filespec?? 
-  save  filename  strinq 
ctory  spec? 

ement  the  string  count 
ce  spec? 

up  to  take  : 

St  for  device 

St  for  directory 

St  for  trailing  character  (:  ]) 

St  offset  in  range  (0-10) 

dataset  descriptor 

address 

count 
nd-star t 

address  next 
if  done? 

b^ck  for  next  segment 
rn  to  caller 


• 
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Appendix  C 

FMS-11  Software  Messages 


This  appendix  provides  general  information  about  FMS-l  1  software  messages 
and  lists  all  of  the  diagnostic  messages  that  FMS  software  can  produce. 

Section  C.2  describes  the  order  of  messages. 

Section  C.3  summarizes  the  types  ol"  messages  each  FMS  software  component 
can  produce. 

Section  C.4  explains  the  procedure  to  tollow  if  FMS  software  malfunctions. 

Section  C.5  includes  messages  for  the  Form  Editor  (FED),  the  Form  Utility 
(FUT),  the  Form  Driver  (FDV).  The  messages,  arranged  alphabetically,  are 
printed  in  the  same  form  that  is  displayed  on  your  terminal. 

C.1    How  to  Use  This  Appendix 

When  you  receive  an  FMS  message,  look  it  up  in  Section  C.5,  read  the  expla- 
nation about  the  reason  for  the  message,  and  apply  the  remedies  that  are 
described.  Message  explanations  are  in  the  left  column  and  remedies  are  in 
the  right  column. 

The  Form  Editor  and  the  Form  Driver  signal  you  with  the  bell  on  your  ter- 
minal in  many  cases.  In  some  cases,  a  message  is  displayed  with  the  bell 
signal,  and  in  some  cases  no  explicit  message  is  available.  Section  C.',]  sum- 
marizes the  ways  the  Form  Editor  and  Form  Driver  use  bell  signals.  Refer  to 
that  section  when  you  hear  a  bell  signal  and  no  message  is  displayed. 

C.2    Order  of  IVIessages  and  Special  Features 

The  messages  in  Section  C.5  have  been  alphabetized  according  to  the  fol- 
lowing convention: 


« 


If  the  first  character  in  a  message  is  not  a  digit  and  not  a  letter,  the  second 
character  ha;-  been  used  for  alphabetizing. 

This  appendix  uses  three  general  references  in  messages  to  stand  for  specific 
names  or  values  that  are  copied  directly  from  the  work  you  are  doing.  They 
are: 


AAAAAA         A  name,  such  as  a  form  name,  tliat  FMS  software  copies  into 
messages. 


C-1 


NNNNNN         A  specific  value,  such  as  a  number  of  blocks  or  bytes,  that  FMS 
software  reports. 

ri  A  sin^Me  digit,  such  as  a  message  code,  that  FMS  provides  to 

distinguish  different  causes  or  contexts  for  a  message. 

If  you  have  trouble  finding  a  message  in  Section  C.5.  review  the  following 
procedure: 


1.  Identify  the  message's  origin.  This  appendix  documents  only  the  messages 
tor  VMS  software. 

2.  If  the  first  character  in  a  message  is  a  special  character,  such  as  a  question 
mark  (?).  ignore  it. 

'■\.     Ignore  any  number  or  name  in  a  message  that  is  specific  to  your  program 
or  files. 

4.     Look  up  the  message  under  the  characters  that  remain. 


C.3    Types  of  FMS  Messages 


Kach  FMS  .software  component  uses  a  special  set  of  conventions  in  the  mes- 
sages it  can  produce.  This  section  summarizes  those  conventions. 

C.3.1    Types  of  Form  Editor  Messages 

The  Form  Editor  can  produce  the  following  types  of  messages: 

•  Messages  that  follow  your  response  to  the  Form  F^ditor's  prompt  are  one  line 
long  and  are  followed  by  the  prompt. 

•  Messages  while  you  are  editing  a  ibrm  appear  on  the  bottom  screen  line. 
Pressing  the  Return  key  removes  the  message  from  the  screen.  You  can  then 
continue  editing. 

•  Messages  after  you  finish  -diting  a  form  appear  on  the  bottom  screen  line 
and  are  followed  by  the  prompt. 

While  you  are  completing  any  of  the  Form  Editor's  questionnaires,  such  as  the 
tield  attribute  questionnaire,  the  following  types  of  P'orm  Driver  messages  can 
also  appear: 

•  Messages  about  invalid  lield  entries  appear  on  the  bottom  screen  line.  You 
can  continue  editing  when  the  cursor  reappears  within  the  tbrm. 

•  Messages  one  line  long  appear  on  the  bottom  screen  line  when  you  press  the 
HEM'  key  to  ask  for  help  about  a  field  in  a  (luestionnaire.  HELP  for  the 
entire  questionnaire  is  displayed  if  you  prc.^s  the  HELP  key  again. 

•  The  Form  Driver  signals  you  by  ringing  the  bell  on  your  terminal  when  vou 


C-2     FMS   1 1  Software  Messages 


use  an  invalid  cursor  control  function  hut  no  message  is  printed.  The  hell 
message  signals  are  summarized  later  in  this  section. 

C.3.2    Types  of  Form  Utility  Messages 

Form  Utility  messages  follow  your  response  to  the  prompt  using  the  following 
form: 

?FUT 


C.3.3    Types  of  Form  Driver  IVIessages 

When  you  are  running  the  Form  Driver  without  dehug  mode  support,  the 
Form  Driver  can  produce  only  the  following  types  of  messages: 

•  Messages  about  invalid  field  entries  appear  on  the  bottom  screen  line,  and 
you  can  immediately  continue  editing  when  the  cursor  reappears  within  the 
form. 

•  Messages  that  are  one  line  long  appear  on  the  bottom  screen  line  when  you 
press  the  HELP  key  to  ask  for  help  about  a  field  in  a  form.  HELP  for  the 
entire  form  is  displayed  if  you  press  the  HELP  key  again. 

•  The  Form  Driver  signals  you  by  ringing  the  bell  on  your  terminal  when  you 
use  an  invalid  cursor  control  function  but  no  message  is  printed.  Bell  mes- 
sage signals  are  summarized  later  in  this  section. 

When  you  are  running  the  Form  Driver  with  debug  mode  support,  each  of  the 
preceding  types  of  messages  can  also  appear,  as  well  as  special  debug  mode 
messages  in  the  following  forms: 

•  ?FDU-F-Text.  (for  fatal  errors). 

•  'i'FDM-W-TeKt  (for  warnings). 

Each  of  the  Form  Driver's  debug  mode  messages  has  a  corresponding  status 
code  that  is  returned  to  the  calling  task.  The  documentaticm  for  each  debug 
message  includes  both  the  MACRO-11  form  and  high-level  language  form  of 
the  status  code.  For  example,  documentation  for  the  message  ""^FDU  F - 
IN>.'ALID  FIELD  SPECIFICATION"  includes  the  following  information: 

Return  code:  FE$FLD  Value:  (-11) 

When  you  have  debugged  a  task  and  are  running  it  without  debug  mode 
support,  the  task  should  include  code  to  test  for  an  error  on  each  Form  Driver 
call  by  checking  the  .status  code.  MACRO  1 1  tasks  should  test  for  the  return 
code.  FE$FLD  in  the  preceding  example.  BASIC  PLUS  2  and  FORTRAN  IV 
tasks  should  test  for  the  value  returned  by  the  FSTAT  call.  11  in  the  pre- 
ceding example. 

The  Form  Driver  can  ahso  return  five  additional  status  codes  that  have  no 
corresponding  debug  mode  messages.  The  codes  and  their  meanings  are: 
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(ode 


Value 


FS$SU(' 

(1) 

FS$INC 

(2) 

(none) 

(-20) 

(none) 

(-21) 

(none) 

(   22) 

Meaning 

Successful  completion. 

Current  form  incomplete. 

Wrong  number  o(  arguments  for  a  FORTRAN  call. 

Impure  area  not  initialized  for  a  FORTRAN  call. 

Output  string  length  too  short  for  BASIC  4  2  call. 


C.3.4    Bell  Message  Signals 

The  Form  ?]dit()r  and  the  Form  Driver  use  the  bell  on  your  terminal  in  slightly 
different  ways. 


C.3.4.1  Bell  Message  Signals  from  the  Form  Driver  —  In  the  debug  mode,  the 
F^orm  Driver  displays  each  debug  mode  message,  rings  the  bell,  and  then  waits 
for  you  to  press  the  Enter  key  or  the  Return  key  before  continuing.  In  the  run 
mode,  the  Form  Driver  does  not  display  the  debug  mode  messages,  does  not 
wait,  and  does  not  use  the  bell  signal;  it  returns  directly  to  the  calling  task. 

In  the  normal  run  mode  (when  the  debug  mode  is  disabled),  the  Form  Driver 
uses  the  bell  to  warn  the  terminal  operator  about  two  kinds  of  input  errors, 
errors  within  fields  and  errors  in  moving  the  cursor  or  in  terminating  fields. 

For  typing  errors  within  fields,  the  Form  Driver  also  displays  a  short  message 
on  the  bottom  line  of  the  screen.  For  example,  when  a  field  description  re- 
quires numeric  characters  and  the  operator  types  a  letter,  the  Form  Driver 
rings  the  bell  and  displays  the  message  NUMERIC  REQUIRED  on  the  bottom 
line  of  the  screen. 

For  errors  in  moving  the  cursor  or  in  terminating  fields,  the  Form  Driver 
warns  the  operator  only  with  the  bell.  The  eight  conditions  that  cause  the 
Form  Driver  to  ring  the  bell  are: 

1.  When  the  Form  Driver  cannot  echo  a  character  ai  the  current  position. 

2.  When  cursor-left  is  illegal. 
.?.    When  cursor-right  is  illegal. 

4.  When  delete  character  is  illegal. 

5.  When  changing  the  current  input  mode  is  illegal. 

6.  When  previous  field  is  illegal  as  a  terminator  becau.se  the  current  field  is 
the  first  field  in  the  form  that  can  accept  input. 

7.  When  next  Held  is  illegal  as  a  terminator  because  the  current  field  is  the 
last  field  in  the  form  that  can  accept  input. 

8.  When  scroll  forward,  scroll  backward,  exit  scrolled  area  downward,  and 
exit  .scrolled  area  uj)ward  are  illegal  because  the  current  field  is  not  in  a 
scrolled  area. 
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C.3.4.2  Bell  Message  Signals  from  the  Form  Editor  —  When  you  are  com- 
pletii.g  any  ot  the  questionnaires  that  the  Form  P^ditor  uses,  the  F'orm  Driver 
displays  the  questionnaire  forms  and  handles  all  terminal  I/O.  Therefore.,  bell 
message  signals  have  the  same  meanings  as  for  the  Form  Driver  when  you  are 
completing  a  questicmnaire.  Refer  to  the  preceding  section  for  Form  Driver 
message  signals  in  the  Form  Driver's  normal  run  mode. 

The  bell  is  also  used  when  the  Form  Driver  is  not  in  control.  The  Form  Editor, 
in  edit  mode,  uses  the  bell  to  signal  illegal  input. 

C.4    Suggestions  to  Follow  If  FMS  Software  Malfunctions 

If  you  think  that  FMS  software  has  malfunctioned,  use  the  following  proce- 
dure. 

1.  As  accurately  as  possible,  write  down  the  functions,  commands,  terminal 
input,  and  user  program  processes  that  you  used  before  the  messages 
mdicating  a  malfunction  appeared. 

2.  Save  any  programs  and  files  that  you  were  using. 

',].  Obtain  new  copies  of  the  FMS  components  that  are  involved,  and  try  to 
duplicate  the  malfunction. 

4.  If  you  still  think  that  FMS  software  has  malfunctioned,  check  your  hard- 
ware or  find  someone  to  check  it  tor  you. 

").  I(  the  problem  persists,  consult  someone  in  your  area  who  is  very  familiar 
with  FMS  software. 

6.  If  you  qualify  to  receive  a  written  reply  under  DIGITAL'S  Software  Per- 
formance Report  (SFR)  service,  follow  the  directions  on  the  SPR  form. 


C.5    FMS  Software  Messages 


Alphabetic  Required 


FDV 


An  alphiibetic  character  is  required  Application  documentation  should  in- 
in  the  current  position.  The  alpha-  elude  instructions  for  completing  the 
betic  characters  are  the  letters  A  -      field. 

Z  and  a  -  /..  and  a  sjjace. 

The  cursor  is  immediately  reposi- 
tioned in  the  field  and  you  may  con- 
tinue ty()nig. 


Alphanumeric  Required 


FDV 


.An  alphabetic  or  numerii'  character      Application  documentation  should  in- 
is  required  in  the  current  poMtion.       elude  instructions  for  completing  the 

field. 


Arravs  not  allowed  in  scrolled  area 


KKI) 


This    message    indicates    that    the  Press  the   Return   key  to  remove  the 

user  has  assigned  the  indexed  at  message    Inuii    the   screen;    the   Form 

tribute  to  a  field  on  a  scrolled  line  Kditor  then   places  the  cursor  in  the 

This  is  not  allowed.  first  field  of  the  (jueslionnaire.  Answer 
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Cannot  overwrite  left  margin 


\  Inr  the  iiuii'Xi'd  iUlrihiitc  lor  each 
lii'ld  ill  the  scroll'.'ii  liiu'.  It  the 
scTolling  <iltril)uti'  is  correct,  continue 
iissif;ninf,'  attriliutes.  If  any  field  in  the 
scrolled  line  is  to  he  an  nulexed  tield. 
exit  troin  the  (|uesti(innaire.  use  the 
NOHMAI,  liuiction  to  remove  the 
scrolling'  altril)ute  troni  the  line,  and 
use  an  ASSI(!.\  command  to  re-enter 
and  complete  the  (juestionnaire.  An- 
swer H  tor  the  indexed  attrilnite  when 
a  lield  is  part  ot  a  horizontal  array, 
and  answer  \'  when  the  lield  is  jiart  ol 
a  vertical  arrav. 


KKI) 


This  message  indicates  that  the  Hetore  trying  the  I  "N'i)KI,LI.\K  tune- 
user  has  done  a  delete  lett  ot  Cursor  tion  ag'''''!.  nio\e  the  lursor  to  a  char- 
to  the  heginninfj  ot  the  line.  'I"he  aiter  |)osition  that  has  enou'jh  hlank 
user  is  attempting  to  undelete-lett  s|)ace  to  the  lett  tor  the  strmg  you 
such  that  the  undelete  string  would  erased, 
go  heyond  the  left  hand  .screen 
boundarv. 


Cannot  overwrite  non-blanks  at  left 


KKI) 


This  message  indicates  that  the 
user  has  done  a  delete  lett  ot  the 
lursor  to  the  heginning  ot  the  hne. 
The  user  is  attempting  to  undelete- 
lett  on  top  ot  non-hlank  characters. 


Cannot  overwrite  non-blanks  at  right 


KKI) 


This  message  indicates  that  the 
user  has  done  a  delete  right  ol  the 
cursor  to  the  end  o!  the  iine.  The 
user  is  attempting  to  undeli'te-right 
on  top  ot  non  blank  characters. 


Cannot  overwrite  right  margin 

KKI) 


This  message  uulicates  that  the 
u.ser  has  done  a  delete  right  ol  the 
cursor  to  the  end  ot  the  line,  '{'he 
user  is  attempting  to  undeh'te  right 
so  the  undelete  string  would  go  be- 
yond the  right  hatui  screen 
boundarv. 


Hetore  trying  the  INDKLLINK  luiic- 
tion  agaui.  move  the  cursor  to  a  char- 
acter position  that  has  enough  blank 
space  to  the  lett  tor  the  string  you 
erased. 


Hetore  trv  ng  the  rNDKKLINK  lunc- 
tion  agaui,  iiK.^e  the  cursor  to  a  char- 
acter position  that  is  blank  and  has 
enough  l)lank  sp.n  .■  to  the  riglit  tor  the 
string  y<iu  erased. 


Hetore  tryuig  the  I  XDKKKIN'K  tunc- 
tion  again,  move  the  cursor  to  a  char- 
acter |)osition  that  has  enough  blank 
space  to  the  right  tor  the  string  >iiu 
deleted. 


Cannot  paste  over  margins  or  non-blanks  or  in  .scrolled  area 

•*KI)  This  message  'udicates  that  the  I'ress  the  Return  key  to  remove  the 
I'ASTK  operation  just  attempted  message  tmni  the  screen  and  to  restore 
by  the  u.ser  has  tailed.  The  u.ser  the  area  that  has  a  reversed  back- 
must  move  the  cursor  to  another  ground,  il  there  is  one. 'i'hen  move  the 
position  in  order  to  complete  the  cursor  to  an  area  that  is  entirely  blank 
I'ASIK.  Hid   is  large  enough  lor  the  selection 

that  vou  want  to  mo\e. 
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(Mear  character  '(('  required 
FKI) 


COMMAND: 

FKI) 


This  iiu'ssage  indicales  that  the 
user  assi^'iied  the  Zero  Kill  attribute 
til  a  tield  with  a  non-zeni  clear 
I'haraeler.  This  is  tint  alloweci. 


This    messafie   is  the    Furm    Kditor 
cnnimand  pniinpt  whiih  sniicits  the 


user  tor  a  eoniiiiaiul. 


Default  too  lonK  for  field 

FKI) 


This  messat,'!'  iiidnates  that  the 
user  has  assigned  a  default  value  to 
the  field  which  is  longer  than  the 
lield  itself.    I'his  is  not  allowed. 


Kmbedded  spaces  illegal  in  form  name 

FKI)  The  torm  name  si)ecified  contained 

embedded   spaces.    This   is   not    al- 
lowed. 

?FKD-F-Full  Duplex  terminal  driver  required 

I'he  Form  F'.dilor  will  not  work  un- 
less the  system  has  the  hdl  duplex 
terminal  drixer. 


?FKD  F  FKD  Requires  VTKM)  terminal 

The  user's  terminal  must  be  a 
V  1100  and  have  been  made  known 
to  the  .svstem  as  a  \  TlOO. 
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If  the  Zero  Fill  attribute  is  correct. 
(  han^e  your  answer  for  the  Clear  ("bar 
attribute  to  '()'.  Il  the  ilear  char.uier 
you  assiijned  is  correct,  change  \oin' 
answer  for  the  Zero  Fill  attribute  to  N. 


The  Form  Kditor  commands  are: 
KDir,  AS.SK.N  AM,.  ASSKA'  NKW, 
ASSICN  FIKLl)  ndnam.  FORM. 
NAMK.  SAVK,  (^111".  and  HKI.l' 
They  are  detailed  m  Chapter  2. 


I'ros  the  Return  ke\  to  remove  the 
messa^'e  troni  the  screen;  then  the 
Form  Kditor  places  the  cursor  in  the 
lirst  lield  of  the  (piestionnaire.  Shorten 
the  detaull  value  to  match  the  lield 
length.  Il  the  lenjith  ot  the  tield  is  cor- 
rect, continue  assi^nm^  attributes.  Il 
the  tield  is  too  short,  exit  trom  the 
questionnaire,  lengthen  the  tield.  and 
use  an  .ASSKiN  command  to  re-enter 
and  complete  the  questionnaire. 


The  user  must  enter  a  valid  (orm  name 
in  the  Form-Wide  .Attributes  (Ques- 
tionnaire. 


RS.\  llM.  supports  onlv  the  lull  du- 
plex terminal  driver:  RSX  llM  \:!._' 
oilers  the  o|)tion  ol  the  lull  duplex  ter- 
minal driver. 


Csi'   the   SKT   I'ommand    to   tell    the 
svstem  the  terminal  is  a  N'TIOO: 

SET      '.'T  I'M'     T  I  : 

or 
SET      TERM-  T  I  C.'T  1  ''0 

The  MCU  np,-niiinn  Manudl  lor  R.S\ 
has  a  lull  descriplion  of  the  SK  T  com- 
mand. 


Return  Code    FK.'rlOI.  \'alue:  (    \)      Cluck  that  tlu'  t(Min  librarv  lile  s|)eci 


All  error  was  encounteri'd  opening      lication  i 


s  correct  and  that  the  tile  ex- 


ihe  form  lilirary.  The  I  ()  error  code  ists  on  the  speciiitd  volume.  Check 
is  returned  in  the  s«'cond  word  oi  that  the  projjer  volume  is  installed  a. id 
the  status  block.  .Xn  error  'ode  ol      thai  lis  device  is  on  ime.  Il  the  device 
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zero  means  that  no  FDH  was  avail- 
able for  the  library.  Otherwise  the 
code  is  as  follows: 

For  F("S;  The  code  tbllows  the 
standard  tor  F(\S  errors  as  a  result 
otOpen  requests.  If  the  high  byte  of 
the  word  is  zero  the  code  is  an  F(\S 
error  code.  If  the  high  byte  of  the 
word  is  non-zero  the  low  byte  is  a 
directive  status  code  (»rror.  The 
word  returned  is  from  F.KHH  of  the 
FDB. 

For  RMS:  The  error  code  is  the 
RMS  error  code  returned  in  the 
STS  word  of  the  FAB  after  the 
$OI'EN  call,  ER$LBY  is  returned  if 
a  form  library  is  active  on  the 
channel  I  Ll'N ). 

7FDV-F-ERROR  READING  FORM  LIBRARY 

Return  Code:  FF:$I0R  Value:  (-18) 
An  error  was  encountered  reading 
the  form  library.  The  I/O  error  code 
is  returned  in  the  .second  word  of 
the  status  block. 

For  FCS:  The  error  code  returned  is 
the  I/O  status  block  code  from  a 
$REAI)  or  $CLOSE  request  on  the 
FDB. 

For  RMS:  This  is  the  STS  word  ol 
the  RAB  or  FAB.  The  call  was  a 
$REAI)  or  .$('L()SE  to  RMS. 

?FDV  F  FILE  NOT  FORM  LIBRARY 


directory  is  corrupt,  use  a  copy  of  the 
form  library  lile  that  is  on  a  working 
volume.  Check  that  the  specified 
channel  number  is  not  currently  in 
use. 


Check  that  the  volume  is  installed  and 
that  its  device  is  on-line.  If  the  mes- 
sage continues  to  appear,  try  another 
copy  of  the  form  library  file.  If  the  new 
copy  works,  the  original  copy  or  its 
form  name  directory  are  corrupt  and 
should  be  replaced.  If  the  message  still 
continues  to  appear,  refer  to  the  proce- 
dures in  Section  C.5  in  this  Appendix. 


The  file  specified  to  open  is  not  a      Check  that  the  file  speci'ication  is  cor- 
forin  library.  The  first  word  was  not      rect. 
RADoO  FLB. 

?Fl)V  F  FORM  LIBRARY  IS  NOT  OPEN  ON  CHANNEL 


Return  Code:  FE$F(^H  \alue:  (  7| 
For  a  call  to  the  Form  Driver,  a 
form  library  is  not  ojjcn 
on  the  specified  channel. 


?FDV  F-ILLECJAL  FOR  DISPLAY  ONLY  FIELD 

Return  Code:  FF:SI)S1'  Value:  (  i;i) 
Input  is  not  allowed  in  a  display 
iiniy  field.  This  error  is  returtied  for 
a  call  to  get  a  lield  if  the  specified 
field  is  (lis|)lay  only,  lor  a  lall  t<i^et 
any  or  all  lields  if  all  fields  in  the 


Check  that  an  FLOPF^N  call  precedes 
the  request  to  display  a  form.  If  the 
form  library  was  properly  opened, 
check  that  the  correct  channel  number 
was  specified  to  the  Form  Driver  (in 
the  last  FL(TMN  call  for  high  level 
languages  and  in  the  F$CHN  argu- 
ment of  the  required  arguments  list  for 
MACRO). 


Check  that  the  field  attribute^  are  cor- 
reit  and  that  the  latest  FSHOVV  or 
FCI-RSH  call  dis|)layed  the  correct 
form.  It  the  call  that  caused  the  mes- 
sage is  an  FCF/r  call,  check  that  the 
call  uses  the  correct  field  identifier. 
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If  the  current  form  contains  a  scrolled 
area,  correct  the  program  logic  so  that 
illegal  Form  Driver  calls  are  not  exe- 
cuted. If  no  form  has  been  referenced, 
check  for  proper  use  of  the  FLOPEN, 
FSHOW,  FCLOSE.  FPUTL  and 
FCLRSH  calls  and  for  improper  flow 
of  control  that  skips  those  calls. 


form  are  display  only,  and  for  a  call 
to  get  any  field  if  the  current  field  is 
display  only. 

?FDV-F-ILLEr,AL  (ALL  TO  FORM  DRIVER 

Return  Code:  FE.^IFN  Value:  (19) 
The  specified  function  is  illegal  in 
the  current  context.  The  calls  to  get 
all  fields,  put  all  fields  is  only 
illegal  for  a  tbrm  with  a  scrolled 
area  if  data  is  specified.  With  no 
data,  it's  legal,  and  to  get  any  field 
are  illegal  if  the  current  form  con- 
tains a  scrolled  area.  Only  the  calls 
to  open  a  form  library,  close  a  form 
library,  display  a  form,  and  to  dis- 
play data  on  the  last  line  are  legal  if 
a  form  is  not  currently  displayed. 

?FDV-F-ILLEGAL  FILE  SPECIFICATION 

Return  Code:  FE$FSP  Value:  {-'A)      Correct  the  file  specification. 
The  file  name  specified  tor  the  form 
library  is  not  a  legal  tile  specifica- 
tion. 

For  FCS:  .PARSE  returned  an  error 
of  .some  type. 

For  RMS:  SOPEN  returned  one  of 
the  following  error  codes:  ER$I)F]V, 

er,<;dir.  er$fnm.  er.sver. 
7fdv-f-impure  area  too  small 

Return  Code:  FESIMP  Value:  (2)  If  the  message  appears  for  a  FOR- 
The  impure  area  specified  is  not  TRAN  IV,  BASIC-h2,  COBOL,  or 
large  enough  to  allocate  the  data  FORTRAN  IV  PLUS  task,  check  that 
structures  required  by  the  Form  the  impure  area  is  at  least  64  bytes 
Driver  to  display  the  form.  larger  than  the  largest  form  the  task 

uses.  If  the  message  appears  for  a 
MACRO  11  task,  check  that  the 
FSIMP  pointer  in  the  Required  Argu- 
ments List  points  to  an  impure  area 
that  is  at  least  as  large  as  the  largest 
form  the  task  uses.  For  MACRO-ll 
tasks  the  first  word  in  the  impure  area 
must  contain  the  size  of  the  impure 
area. 


?FDV  F-INVALID  CALL  TO  GET  NAMED  DATA 

Return  Code:  FE^DMN  Value:  Check  for  a  program  error  that  causes 
(1"))  A  call  to  get  named  data  is  the  call  to  be  executed  when  the  cur- 
invalid  for  one  of  the  following  rea-  rent  form  is  the  wrong  form.  Check  for 
sons:  the  correct  name  in  an  FNDATA  call 

and  the  correct  index  value  in  an  Fl- 

•  no  named  data  exists  tor  the  cur-  DATA  call 
rent  form. 

•  the  data  name  specified  does  not 
exist. 

•  the  index  specified  does  not  exist. 
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?FDV-F-INVALn)  CHANNKL  NIMBER  SPECIFIED 

Hclurn  Code:   KK$ICH  \alui';  (   (i)      Correct  the  channel  number  the  task 
I'he  channel  number  specified  in  a      is  usinji  or  specily  a  dit'terent  range  ol 
call    to  the    Form    Driver   is   not    a      channels  Ibr  your  application, 
valid  channel  number  for  the  task. 
Second   word  of  status  bloi  k  con- 
tains   the    I/O    status    code    Irom 
.system  in  the  event  of  an  error. 

For  F(^S:  The  error  code  is  from  the 
F.KRR  offset  of  the  FI)B. 

For  RMS:  'I'he  error  code  is  from 
the  STS  word  of  the  FAB. 

?FDVF  INVALID  FIELD  SPECIFICATION 

Return  Code:  FK.SFLI)  Value:  (III  Check  the  lield  name  or  array  index. 

The  field  specified  does  not  exist.  Also  check   tor  a   profjram  error  that 

An  invalid  tield  name  or  an  invalid  causes  the  call  to  be  executed  at  the 

index  for  the  field  was  specified.  wrons  time  or  tor  the  wronj^  tbrm. 

?FDVF  INVALID  FIRST  LINE  TO  DISPLAY  FORM 


Return  Code:  FKSLLN  Value:  (  10) 
The  entire  form  will  not  lit  on  the 
screen  if  displayed  starting  at  the 
line  number  specified  in  the  call  to 
the  Form  Driver  or  the  line  number 
is  not  from  1  to  2:i  inclusive. 


Check  that  the  terminal  has  the  fea- 
tures you  need  and  is  .set  properly  for 
the  form  you  want  to  use.  Check  for  a 
program  error  that  causes  the  wrong 
starting  screen  line  number.  For  forms 
that  are  to  be  offset  on  the  screen, 
check  that  the  associated  help  forms 
are  properly  designed  for  the  full  range 
of  offset  positions. 


7FDV-F-INVALID  FORM  DEFINITION 


Return  Code:  FF'.SFRM  Value:  (  8)      Refer  to  the  procedures  in  Section  C.5 
The  format  of  the  form  description      of  this  Appendix, 
is  not  valid. 


?FDV  F-INVALID  FUNCTION  CODE 

Return  Code:  FF]$FCD  Value:  (1) 
'I'he  function  code  specified  for  a 
call  to  the  Form  Driver  does  not 
exist. 


7FDV-F-NO  FIELDS  DEFINED  FOR  FORM 

Return  Code:  FFl.SNOF  Value: 
(-12)  Calls  i)ertaining  to  fields  are 
illegal  if  no  fields  are  defined  tor  the 
current  form. 


If  a  MACRO  11  task  caused  the  mes- 
sage to  appear,  check  for  a  typing  error 
in  the  function  code.  If  the  function 
code  is  correct  or  if  a  FORTRAN  IV  or 
a  BASIC  I'LCS  2,  COBOL.  FOR- 
TRAN IV  PLCS  task  caused  the  mes- 
sage to  appear,  refer  to  the  procedures 
in  Section  C..")  in  this  Appendix. 


Check  that  the  form  has  beer  designed 
l)roperly.  Also  check  tor  i  |)rogram 
error  that  causes  the  f'ielfi  processing 
call  to  be  executed  for  the  wrong  form. 
For  example,  check  for  consecutive 
FSHOW  calls  that  display  more  than 
one  form  on  the  terminal  screen  simul- 
taneously but  display  a  form  that  has 
only  constant  text  last. 
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7FDV-F-SPECIFIED  FIELD  NOT  IN  SCROLLED  AREA 


Return  Cc.de:  FE$NS{'  Value: 
(-14)  The  name  of  a  field  is  re- 
quired to  identify  the  scrolled  area 
the  call  pertains  to.  The  specified 
field  is  not  in  a  scrolled  area. 

7FDV-F-UNDEFINED  FIELD  TERMINATOR 

Return  Code:  FE$UTR  Value: 
(-17)  The  field  terminator  code 
specified  in  a  call  lo  process  a  field 
is  less  than  0  or  greater  than  9. 

7FDV-F-UNDEFINED  FORM 

Return  Code:  FR$FNM  Value:  (-9) 
The  specified  form  is  not  defined. 


?FED-F-Error  reading  input  form  file 

An  I/O  error  was  returned  from  a 
call  to  read  the  input  file. 


?FED-Form  being  saved 


FED 


This  message  indicates  to  the  user 
that  the  torm  has  begun  the  process 
of  being  written  to  the  output  de- 
vice. 


Form  is  not  in  propei  format 


FED 


The  specified  Ibrm  is  not  in  the 
proper  format  and  therefore  cannot 
he  edited. 


?FED-Form  not  saved  on  Ql  IT 


FED 


This  message  indicates  to  the  u.ser 
that  when  a  IJIIT  operation  has 
been  executed  the  form  that  was 
being  edited  was  not  saved. 


Full  Field  Required 


FDV 


The  current  field  must  be  com- 
pletely filled  and  contain  no  till 
characters, 


Check  the  current  Ibrm.  If  the  form  is 
correct  and  if  it  has  been  designed 
properly,  check  for  a  tyjjing  error  in 
the  field  name. 


Correct  the  field  terminator  code. 


Check  that  the  correct  form  library  file 
is  open  and  that  the  channel  number 
specified  to  the  Form  Driver  is  the  one 
s))ecified  when  the  form  library  file 
was  opened  and  that  the  call  specifies 
the  correct  iorm  name. 


Check  that  the  form  library  volume  is 
installed  and  that  its  device  is  on-line. 
II  the  message  continues  to  appear,  try 
another  copy  of  the  form  library  file.  If 
the  new  copy  works,  the  original  copy 
should  be  replaced.  Il  the  message  still 
continues  to  appear,  refer  to  the  proce- 
dures in  Section  Co  in  this  Appendix. 


The  message  is  for  information  only. 
HT  onlv. 


Check  that  your  input  tile  specifica- 
tion is  correct  and  check  tor  a  bad 
block  in  the  tile.  Also  try  using  a  copy 
ot  the  file  that  does  work  with  the 
Form  Editor  or  Form  Driver.  Il  the 
message  continues  to  appear,  reter  to 
the  |)rocedures  in  Section  C.o  in  this 
Appendix. 


The  message  is  tor  inlormation  only. 


Application  documentation  should  in- 
clude instruclions  tbr  ((impleliiig  the 
field. 
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?FED-IllegaI  command  line 

FED                      The  syntax  of  the  command  line 

Retype  the  command  line  correctly.             ^^V 

entered  in  response  to  the  "FED    " 

Use  /lO   to  get   the  version  number; 

prompt  was  invalid. 

/CR  to  create  a  new  form. 

?FED-Input  file  is  not  form  file  or  form  library 

F'ED                       The   specified   input    file   is   not   a 

Check  the  input  file  specification. 

valid  form  file  or  form  library. 

?FED  F-Insufficient  Memory 

This  message  indicates  there  is  not 

There    must    be    at    least    twice    the 

enough    memory   to   create   a   new 

memory  required  fo.   a  form  descrip- 

form or  to  edit  the  specified  form. 

tion  for  any  editing  to  take  place. 

?FED-F-Invalid  form  name 

The  form  name  was  longer  than  6 

The  form  named  specifed  in  response 

characters  or  was  all  spaces. 

to  the  Form  ri-amp'''  prompt  (after  a 
form  library  file  was  specified  as  the               ^^^ 
input    file)  was  not  valid  as  a  form              ^^B 
name.                                                                    ^^^ 

?FED-F-Unable  to  attach  terminal 

The  Form  Editor  is  unable  to  at- 

Check to  see  if  there  are  too  many  ter- 

tach the  user's  terminal,  therefore 

minals   attached,    or   too   many   pro- 

cannot proceed. 

grams  running  or  if  some  other  task 
has  your  terminal  attached. 

?FED-F-Unable  to  create  output  file 

The  sperifi-.'d  output  file  cannot  be 

File  can't  be  created  for  many  possible              ^^B 

created 

reasons:  not  enough  disk  space,  a  pro- 
tection violation,  hard  error. 

?FED-Unabie  to  open  input  file 

FED                      The  specified   input   file  does  not 

exist     or    cannot     be    opened     for 

editi;'K 

?FED  Write  error  —  output  file  not  saved 

^ 

FED                       This  message  indicates  that  there 

Check  that  the  output  volume  is  prop-              ^^^ 

was  an  error  writing  to  the  output 

erly  installed  and  that  its  device  is  on- 

file and  that  the  form  was  lost. 

line  and  write-enabled.  If  a  hardware 
problem  has  caused  the  message  to  ap- 
pear, contact  your  DIGITAL  service 
representative. 

7FDV-W  DATA  TOO  LONCJ 

Return     Code:     FH$D1.N     Value: 

Check  for  program  errors  that  cause 

t    IH)  'I'he  data  specified  to  output 

the  data  string  to  be  too  long.  Check 

is  loo  long.  The  Form  Drixtr  trun- 

that  the  form  has  been  designed  prop- 

cites the  data  and  proceeds. 

erly. 

?FIIT  -  Clear  character  invalid  Field  name        AAAAAA 

The  named  fielii  iias  the  Zero  Fill 

See    "FUT    -      Invalid    form    header 

attribute,    but    "(('   is   not    the   as- 

format." 

signed  clear  character. 

^^ 

?FUT  —  Command  file  depth  exceeded 

• 

A  third-level  indirect  command  file 

Combine  two  of  the  indirtvt  command 
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sp/i'ciries  iiiidtlier  iiuliri'it  ('(mimand 
till'.  Iiuliri'ct  command  iiles  for  the 
Form  I'tility  may  hv  nestt'd  to  a 
doptli  ol  three. 

?P'l'T  —  Command  file  error  unrecognized 

The  iiidireet  commaiul  file  proc- 
essor has  returned  ar  error  code 
that  the  Form  I'tility  cannot  un- 
derstand and  handle. 


?Fl  T  -    Command  file  I/O  error 


Iiles  that  you  tried  to  use,  or  revise  the 
set  ol  indirect  command  tiles  so  that 
no  more  than  three  are  executing  at 
one  lime. 


("onCirm  that  each  line  in  the  indirect 
command  files  that  you  are  usin^j  is 
valid.  If  the  messajje  appears  tor  a  file 
that  you  are  sure  is  correct,  complete 
the  procedure  in  Section  (\4. 


An  I/O  error  occurred  when  readinf^  Follow  the  procedures  that  have  been 
an  indirect  command  tile.  Two  established  to  cover  possible  hardware 
lauses  for  this  messafje  are:  errors  on  your  system. 

•  A  l)ad  I/O  device. 

•  .A  bad  l)lock  on  an  I/O  volume. 


'FUT  —  Command  file  illegal  file  specification 

The    specification    tor   an    indirect 
command  file  is  invalid. 


?FCT     -  Command  file  line  too  long 


.■\  line  in  an  indirect  command  file 
is  longer  than  i:!2-character  max 
imum  length.  A  cause  for  this  mes- 
sage is  a  line  that  is  longer  than  I'.Vl 
characters,  although  each  |)art  may 
be  shorter  than  that. 


*Fl'T  —  Command  file  open  error 


Fxamine  all  indirect  command  file 
specifications,  including  those  in 
nested  indirected  command  files, 
("heck  for  typing  errors  and  for  specifi- 
cations that  are  correct  on  another  op- 
erating system  l)ut  not  legal  on  the 
.s\stem  that  vou  are  using. 


Break  the  overlength  line  by  repeat inj, 
its  command  in  separate  lines.  Or 
.'eorganize  the  indirect  command  file. 


'{"he  Form  I'tility  could  not  find  a  Check  that  all  indirect  command  tile 

specified  indirect  command  file  or  specifications    are    correct    and    com- 

tound  it   but  could  not  open  it.  If  plete,  and  check  that   the  default  or 

ihe  system  has  locked  the  indirect  ex|)licit  volumes  are  installed  and  on- 

commaiid  file,  the  P'orm  I'tility  dis-  line.  I'se  I'll*  to  check  for  an  indirect 

plays  this  message.  command  file  that  is  locked. 


'FIT  —  Default  text  too  long  Field  Name      AAAAAA 

The  named  field  has  a  default  value      See    "Fl'T 
that  is  longer  than  the  iielil  can  dis-      format." 
play. 


Invalid    form    header 


'FIT  —  Display-Only  field  is  full  or  required  Field  name      AAAAAA 

Invalid 


The  named  field  has  the  Display 
Only  attribute  and  also  the  Must- 
Fill  attril)ute  or  the  Response  Re- 
quired attribute,  a  conibinalion  of 
attributes  that  is  invalid. 


See    -FIT 
format .  " 


irm    header 
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'Fl"I'        Krror  closing  inpiil  Tilo 


lilt'  lilr  In  iiMiiiiir-.  lliai  Mi|i|)(irl  Knr  each  mpnt  lilc.  ihfi  k  I  lie  (lii-c(  iiif\ 
ihi'  I'niin  I  iihis  (Icitnlfd  an  ciTur  cnlrv  Ini'  inlnriiial  icii  aliniit  the  lilr 
uhilc    I  Ill-Ill^    an    miml     lilc.     I'un       licini;   Imkcd  or  iinu-^alilc,    Al-n  1 1\    In 

make  a  i<i|n   ni  en  li   input    lili',   ll   all 
input    \[\f>    (ail    lie    i^picd.    ri'ti\    the 


I'.iioo  Inr  ihi>  nifssai;!'  arr: 

•  A  liad   mpiil   !ilc  dcv  uf, 

•  A  inni  lilnik  (Ml  an  inpiii  \(i1uiih 


Knriii  I'liliiv  iipcraiiiin  ih.ii  nrii^malK 
tailed  It  I  he  I'nnn  I'liliiv  npcialKin 
-till  taiU,  chfck  Ihc  pi(i(  1  (lui'f  in  Scc- 
tHUi  r.  1. 


•FIT  -    Error  rlosiriK  or  spooling  oiHput  file 


'I'hc   file   I  ()  nmlint's   that    ■^iippmi  I'ia     u-in^    a    diticrfnl    output    dc\  ice 

the  Form   I'lilitN-  (li'iccicd  .w)  ciroi  and  \olunu'.  ll  tlic  m('vsii>;c  continut's 

while  closing'  or  spodlm^  an  oiil|>ui  to  ap|)eai'.   Inllow    the  proeednro  tliat 

tile.    Two    (allies    tor   thi-    inc»a^c  have    been    e-tahlished    to    cover    pos- 

are;  --ihle  hardware  error>  on  \dur  >\stem. 

•  A  had  ouif)iii  or  -pooling;  devn c. 

•  A      had      hlock     on     an     output 
\o|uinc 


'KIT    -  Krror  n'adiiiK  inpu(  file 

rile  tile  1  O  roulmes  that   support       See    the    causes    and    su<;^'esti(iiis    lor 
ihe  Form   I'tility  delectecl  ati  error         Fl    1'        Krror  closing  input  lile." 
while  reading  an  input  tili'. 

•Kl'T  —  Krror  writing  output  Tile  block 


'l"he  lile  1  ( )  routines  that  -uppori 
the  Form  I'tililv  delected  an  error 
while  writ  in;,'  an  output  tile  block. 


■^ee    the    causes    and    suggestions    lor 
"I'l    I  K.rror    closing'    or    sixiolinjx 

output  tile." 


■.'KIT  -    Krror  writing  record  to  output  file 


The  lile  1 0  routines  that   support       See    the    causes    and    su^'^'estions    tor 
the  Form   I'tility  detected  an  em  r       "Fl'T  Krror    closing    or    spooling' 

while  writing  an  output  lile  record.         output  lile." 


?Kl'T  —  Kield  beyond  screen  Kield  name      AAAAA.V 

The    named    lield    extends    l)ey(ind       See    "Fl  "I" 
column  HO  and  the  torm  has  the  SO-       tormat.  ' 
column  atlril)ute. 


iiualid    lorm     header 


?KrT  —  Korm  no'  in  library 


The  input  form  lihrarv  lile  -,  pec  died  I  m'  the  1,1  optio  i  with  the  input  lorm 
in  the  Form  I'tility  picmpi  dues  library  'di'  tiaiiie  to  list  the  names  of 
not  c(/ntain  the  torm  vou  re(|ue?'"(l.       all  lorm  ■  ui  the  lorm  library  lile.  'I'heii 

t\  pi'  anot  lu"'  Idrm  name. 


".'KIT  -  Korn>  AAAAAA  replaced 


I'he  (lescrii)t;on  lor  the  named  lorm        The  message  is  onl\   lor  voiir  inlorma- 
has    been    re|)laced    in    the    named       tion. 
torm  hbrarv  lile. 
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?FUT  —  Illegal  command 


'I'hf  conimatiri  lino  s\ntax  is  inior- 
rt'tt.  Some  causos  lur  this  nu'ssa^'f 
a  re : 

•  More  than  one  output  file  speci- 
fied. 

•  No  charaeters  in  cninniand  line. 

•  Command    line    includes    both    a 
tile  speeitieat'on  anvi  the  /Ilj  o 
/HK  option. 

•  Command  line  with  the  FF''  (op- 
tion includes  an  output  I'ile  speci- 
f'icatio.,. 

•  No  output  file  specified  for  '('H. 
/I)K.  /KX.  /OB.  or    HP  options. 


Correct  the  command  line 


?FUT  -  Illegal  file  specification 

.An  input  or  output  file  specification 
is  incomplete  or  contains  illegal 
characters.  Wildcard  characters  in 
a  file  si)ecification  cause  this  mes- 
sage, 

?FIJT  —  Illegal  input  file  specification  or  option 

.•\n  input  file  specification  is  in- 
valid, or  an  option  is  irnalid. 

?FUT  —  illegal  output  file  or  option 

The  output  tile  specitication  is  in- 
valid, or  an  option  is  invalid.  Some 
causes  tor  tfiis  messafie  are: 

•  The  .'SI*  option  is  included  with 
another  option  that  produces  no 
printable  output. 

•  The  /HA  option  is  included  with 
another  option  that  produces  no 
form  library  files. 

•  Options  such  as  /CH  and  /1)K 
conllict. 

?Fl'T  —  Illegal  replacement  of  form,  use  /RP 

'I'he  Form  Ctility  command  floes 
not  include  the  /HI'  option  hut  tries 
to  replace  a  tbrm  description  that  is 
in  the  torm  library  tile  specified  in 
the  Form  I'tility  prompt.  One 
cause  for  this  message  is  combining 
two  form  library  tiles  that  contain  a 
torm  description  with  the  same 
name. 


Remove  an>  wildcards  that  are  in  the 
tile  specitications,  and  check  the  file 
s|)ecifications  for  the  file  names  and 
types  that  are  retiuired  for  the  oi)tions 
that  you  are  using. 


Check  the  input  file  specifications  and 
options  tor  typing  errors. 


Check  the  output  file  specitication  foi 
typing  errors.  Check  that  the  ojjtions 
are  consistent  with  one  another. 


Cse  the  '\A  ojition  to  check  the  names 
of  all  forms  in  the  input  files.  Cse  the 
I)K  option  to  delete  inibvidual  form 
descriptions.  Or  use  the  AW  option  to 
coml)ine  form  library  Ides,  and  pre- 
serve only  the  last  form  description 
processed  for  each  (iu|)liciite. 
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?Fl!T  —  In  form  library      AAAAAA.  Form  name      AAAAAA 


I'his  nu'ssiific  api)i';irs  onls    ns  tho 
first  line  ol  a  Iwo-line  nu'ssafje. 


Sec  till'  description  for  the  other  mes- 
sage that  the  Form  I'tility  has  dis- 
played. 


?FIJT  —  Insufficipnt  memory 


Althdufih  the  Korni  I'tility  can  run, 
there  is  too  little  memory  to  process 
any  form  descriptions.  In  addition 
to  the  Form  I'lility's  hasic  retjuire- 
ments,  it  recjuires  enmit;h  memory 
lor  a  lorm  library  file  directory  and 
one  form  description. 

Insufficient  space  for  output  buffer 

See"Fr'l"       Insullicient  memory." 
Invalid  field  descriptor 

See  "FTT  Invalid  form  header 
format ." 

^Fl^T  —  Invalid  fixed  decimal  picture  Field  name      AAAAAA 


Ask  your  .system  manager  to  check 
whether  the  Form  lUility  has  been  in- 
stalled as  a  check-pointable  task.  The 
Form  I'tility  should  always  be  check- 
l)ointable.  Install  or  run  the  Form 
I'tility  with  a  larf^er  memory  incre- 
ment . 


TII 


Fl'T  - 


'.'FIT 


The  named  lield  has  the  Fixed  Dec- 
imal attribute  but  the  field  [)icture 
is  iinproper  for  one  ot  the  (ollowiufj 
reasons: 

•  There  is  no  decimal  point, 

•  There  are   two  or   more  decimal 
points. 

•  The  first  and  last  picture  charac- 
ters are  not  'H'. 


See    -VV 
tormat." 


Invalid    lorm    header 


?FUT   —  Invalid  form  description 


See  "Fl'r        Invalid  form  header 
format." 


?FUT  —  Invalid  form  header  format 


The  Form  I'tility  has  detected  an 
error  in  the  form  description  format 
and  stop|)ed  processing  the  form 
description.  The  form  with  the 
error  may  have  been  corru()ted  l)y 
I/O  or  device  errors  and  cannot  be 
used  with  an  FMS  ap|)lication. 


First,  try  to  recover  the  form  descrip- 
tion by  using  an  earlier  version  of  a 
form  description  file  or  torm  librarv 
file. 

If  all  versions  of  the  form  description 
cause  this  message  or  similar  ones,  use 
the  following  procedure: 

1.  Retype  the  form  completely  with 
the  Form  Kditor.  Do  not  try  to  edit 
a  version  that  causes  the  inessage. 

1.'.  If  problems  |)ersist,  refer  to  Section 
C.-l. 


?KIIT  —  Invalid  form  name 


The  last  form  name  you  typed  con-       Type  a  valid  form  name. 
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tains  characters  that  are  not  valid. 
pAamples  ol  causes  of  this  message 
are: 

•  Inchiding   a   non-Radix-nO   char- 
acter. 

•  Responding  with  an  asterisk  (*) 
after  using  the  /KF  option. 


?FUT  —  Invalid  index  value  Field  name      AAAAAA 

The   two   causes   for   this   message      See    "FUT 
are:  format." 

•  The  named  field  has  the  vertical 
(indexed)  attribute  and  the 
lowest  element  of  the  array  is 
below  the  last  line  that  is  cur- 
rently assigned  for  the  form. 

•  The  named  field  is  in  a  line  that 
has  the  .scrolling  attribute  and 
the  scrolled  area  is  only  one  line 
long. 


[valid    form    header 


?FUT  —  Invalid  named  data  section 


See  "FUT  —  Invalid  form  header 
format." 


?FUT  —  Invalid  number  of  fields 


See  "FUT  —  Invalid  form  header 
format." 


?FUT  —  Invalid  text  section 


See  "FUT  —  Invalid  form  header 
format." 

?FUT  —  Logic  error  -  Exception  stack  overflow 

P'oUow    the    procedure    in    Section 
('.4. 

?FUT  —  Logic  error  -  Exception  stack  underflow 

Follow    the    procedure    in    Section 
C.4. 

?FIIT  —  Logic  error  -  pass  2  illegal  file  number 

Follow    the    procedure    in    Section 
CA. 

?FUT  —  Logic  error  -  pass  2  too  few  input  files 

Follow    the    procedure    in    Section 
(■.4. 

?FUT  —  Not  a  valid  form  file  or  library 

An  input  file  does  not  contain  the      Check  eai  h  input  file  specification  for 
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piopor    rodi'    words    that     icicntity 

ly|)ing  errors,  and  check  for  acciden- 

tiMin (Ifsciiption  files  and  lorm  li- 

tally    having    typed    the    wrong    tile              ^^^ 

lirafv  lilt's. 

^^^ 

?FUT  -  No  forms  in  library 

Alter  specityiiiK  the  /("H.  /DK.  /FA. 

Type  a  command. 

or  /RF  option  to  create  a  toriii  li- 

brary file,  you  extracted  no  tonus 

for  the  output   form  lilirary  tile  or 

deleted    all    tonus    from    the    input 

form  library  files.   The  message  is  a 

warning  that  your  st)ecified  out|)ut 

form  library  lile  has  not   been  tre- 

ated. 

?Fl'T  —  Right-justified  field  with  mixed  picture  Fi 

ield  name      AAAAAA 

'i"he  named  field  has  both  the  rijiht- 

See    "Fl'T     -    Invalid    form    header 

justilied  attribute  and  a  mixed  |)ic- 

lormat." 

ture.  The  idinbination  is  invalid. 

^^ 

'.'FIT  —  Scrolled  and  array  field  Field  name      AAAAAA                                                                     ^^^ 

The  named  tield  has  the  horizontal 

See    "Fl'T          invalid    form    header 

or  vertical  (indexed)  attribute  and 

format." 

is  also  located  in  a  line  that  has  the 

scrolling  attribute. 

1 

'.'FIT  —  Unable  to  delete  output  file 

When  a  Form  I'tility  process  fails. 

See    the    causes    and    suggestions    for 

the  Form  I'tility  usually  deletes  the 

"FUT          Krror    closing   or   spooling              ^^^ 

partially  complete  output    tile  be- 

^^B 

cause  it  is  tault>.  This  message  ap- 

^^ 

pears  when  the  delete  action  cannot 

be  completed. 

'.'FIT  —  Unable  to  open  input  file 

See  "Fl'T         Krror  reading  input 

file." 

'.'FUT  —  I'nable  to  open  output  file 

^ 

See    "Fl   r            Krror    closing    or 

• 

spooling  output  file." 

?FIT  —  Unable  to  reopen  input  file 

Follow    the    procedure    in    Section 

c.t. 

'.'FUT  —  Zero  length  field  field  name      AAAAAA 

The  named  field  is  zero  characters 

See    "FUT          Invalid    form    header 

long. 

format." 

Illegal  Command 

FKI) 

'I'his    mes.sage    indicates    that    the 

Press  the   Return   key  to  remove  the 

user  has  typed  an  illegal  command 

message  from  the  screen.  The   Form 

in      response      to     a      i  DMI^AND: 

Kditor       then       redisplays       the               ^^^ 

promjit. 

COMMAND:    prompt.   'lype   in  any  of               ^^B 

C-18 
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Input  Required 

FDV 


At  least  one  non-fill  character  must 
he  entered  in  the  current  lield. 


Insert  line  not  allowed 


FED 


This  messajje  indicates  that  the 
user  attempted  either  an  Undelete- 
Line  or  an  Openline  when  the  last 
line  was  non-blank. 


Insert  not  allowed 


FED 


This  message  indicates  that  the 
user  attempted  to  insert  a  character 
when  the  last  character  on  the  line 
was  not  blank. 


Invalid  picture  for  a  flxed  decimal  fleld 


FED 


This  message  indicates  that  the 
user  has  assigned  the  fixed  decimal 
attribute  to  a  field  whose  picture 
does  not  meet  the  requirements  lor 
this  attribute. 


the  Form  Editor  ccmimnnds. 

Type  HEM'  to  get  a  list  ol  the  valid 
commands. 


Ai)plication  documentation  should  in- 
clude instructions  tor  com|)leting  the 
field.  Press  the  Return  ke\  to  remove 
the  message  from  the  screen:  the  Form 
Editor  then  disi)la\s  the  cursor  in  the 
field  you  must  complete, 


I'ress  the  Return  key  to  remove  the 
message  from  the  screen;  then  the 
Form  Editor  places  the  cursor  where 
the  function  failed.  The  way  you 
should  continue  dejiends  on  your  form. 
For  example,  you  may  erase  part  of 
the  form  below  the  current  line,  or 
raise  the  text  and  fields  in  the  form  by 
erasing  part  of  the  form  above  the  cur- 
rent line. 


Press  the  Return  key  to  remove  the 
message  from  the  screen;  then  the 
Form  Editor  places  the  cursor  where 
the  insertion  failed.  The  way  you 
should  continue  depends  on  your  form. 
For  example,  you  may  switch  to  the 
OVERSTRIKE  mode,  or  continue  in 
the  IN'SER'I"  mode  and  erase  part  of 
the  current  line. 


IVess  the  Return  key  to  remove  the 
message  from  the  screen;  then  the 
Form  Editor  places  the  cursor  at  the 
first  field  in  the  questionnaire,  '"hange 
the  i'nswer  to  the  Fixed  !)<■  •  -'.estion 
to  N.  If  the  field  is  not  a  I'wvd  'ieiimal 
field,  continue  assigning  attributes.  If 
the  field  should  l)e  a  fixed  decimal 
field,  exit  from  the  quest ioiuiaire.  cor- 
rect the  field  picture,  and  use  an  AS- 
SKiN  command  to  re-enti'r  and  cnm- 
plete  the  ()uesfiomiaire. 

The  requirements  for  a  fixed  decimal 
field  are: 

•  A  numeric  lield. 

•  Exactly  one  embedded  decimal 
point  the  decimal  jximt  cannot  be 
in  either  the  first  or  last  character 
position  in  the  field. 
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Logic  error  —  bad  field  data  character 

FKI)  This  iiu'ssagc  indiciiles  thiit  an  un- 

known field  iharacter  was  touiul  in 
a  lii'Id.  It  this  dccurs  it  means  that 
the  screen  image  was  probably  al- 
tered by  some  external  disturbance. 

New  form  exceeds  available  memorv  —  form  lost 


Him  the  memory  diafjnosfirs  and  no- 
tify your  DKilTAL  service  rejjresenta- 
tive. 


KKl) 


You  created  a  form  that  was  too 
large  for  the  Form  Editor  to  process 
with  the  memory  available.  Ihe 
form  is  lost. 


'I'here  is  no  wav  to  recover  the  form. 


NO  HELP  AVAILABLE 


FDV 


No  further  HKLI'  is  available  for      Ap|)lication  documentation  should  in- 
the  current  form.  dude  instructions  for  the  operator. 


Non-Displayable  Character 


FDV 


No  validation  is  required  in  the  cur-  A|)plication  documentation  should  in- 

reni    position.    However   the   char-  dude  instructions  for  completing  the 

acter  entered  cannot   be  displayed  field, 
and  is  therefore  invalid. 


Numeric  Required 


FDV 


A   numeric   character   (0  9)   is   re-      Application  documenfati(m  should  in- 
cpiired  in  the  current  position.  dude  instructions  for  completing  the 

field. 


Only  NNNNNN  memory  blocks  left.  Continue  (Y,N)  ? 


FED 


This  message  indicates  that  only  a 
small  amount  of  memory  (the  spec- 
ified number  of  512  byte  blocksl  is 
available  to  increase  the  size  of  the 
form.  The  u.ser  is  given  the  option 
of  continuing. 


Repeat 

FED 


This  is  the  Form  Flditor  REPEA'I' 
prompt,  which  indicates  that  the 
u.ser  has  typed  (;OIT)/'"digit". 


Right  justified  is  illegal  for  a  mixed  picture  field 


FED 


This  tnessage  indicates  that  the 
u.ser  has  assigned  the  right  justified 
attribute  to  a  mi.xed  picture  field. 
This  is  not  allowed.  The  user  must 
type  a  character  lo  continue  and 
the  field  attributes  will  be  redis- 
played and  the  u.ser  must  enter 
"N"  to  the  right  justified  attribute. 


Type  N  to  cancel  the  file  specification 
string.  The  Form  Editor  then  prompts 
you  for  another  file  specification 
siring.  Type  V  to  proceed  with  the 
Form  Editor  session.  However,  if  your 
editing  increases  the  form  size  l)y  too 
iTiud  the  Form  Editor  will  not  warn 
you  and  your  editing  work  will  be  lost. 


All  the  following  digits  will  be  saved 
and  the  first  coinmand  key  typed  after 
the  digits  will  be  re|)eated  that 
number  of  times. 


I'ress  the  Return  key  to  remove  the 
message  from  the  screen;  then  the 
Form  Editor  places  the  cursor  at  the 
first  field  in  the  questionnaire.  Answer 
the  Right  .lust  question  N.  It  the  field 
should  have  a  mixed  i)icture.  continue 
assigning  attributes.  If  the  field  should 
not  have  a  mixed  picture,  exit  from 
the  ((uestionnaire,  change  the  field 
picture  (perhaps  by  dividing  the  IielJ 
into  separate  fields),  and  use  an  AS- 
SKIN  command  to  re-enter  and  com- 
plete the  ((Uestionnaire. 
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Signed  Numeric  Required 


FI)\ 


VIDKO 


A  \alicl  >i^ii('cl  numeric'  character  Applicatitm  documentalidn  should  in- 
ci  M.  "  ".  '■  ".  "•■■!  IS  required  in  ilude  instructions  lor  ccnipletint,'  the 
the  current  position.  tield. 


1-KI) 


'I'his  IS  the  Korm   F-ditor  video  at-      Tlie  user  must   respond  with  either  a 
trihute  i)rompt.  video  attnhule  or  press  the  KNTKK 

ke\  to  return  to  editing. 
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building  api)lications.  5-21 
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assigning,  2  24 

Form  Driver.  4   1 1 

Form  Driver  |)rocessing  ol.  4  8 

Form  Kditor,  2   14 

Downarrow  key. 

Current  screen,  as  a  lorni-wide 

Form  Driver.  4-17 

attribute,  2  20 

Form  Kditor,  2   12 

Cursor, 

initial  position  of.  4   12 

moving  witb  Form  Driver.  4   1.'? 

4    15  to 

4   H) 

Fcho  off  attribute. 

Cl'T  operation.  2   15 

assigning.  2  24 

Form  Driver  processing  of.  4  8 

1^ 

P'.Drr  command  (Form  Kditor).  2  7 

Data. 

Kdit  status  display.  2-8 

overlengtb.  (i   Hi.  ti  21 

Kditing  forms.  2  7 

\alidating,  H-16.  (i  21 

Finding  line,  assigning.  2  21 

Data  declarations  COBOL.  ;M2, 

5  24 

KNTKK  function.  4   14 

Data  length.  5  41 

EOL  operation.  2  12 

Data  types  tor  Form  Driver  arguments,  fv  IH 
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Data  value  pointer.  r)-40 
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Debug  mode. 

field  values.  4-1.'? 

^^ 

choosing.  8-7 

lines.  2-14  to  2-15 

w 

error  status.  n-'I 

restoring  after.  2-15 

Form  Driver.  4   10 

Krror  messages. 

using,  n  2 

complete  listing.  C-1 

Default  attribute,  assigning,  2-2;^ 

display  by  P'orm  Driver.  ()-2.'i 

Default  field  values. 

Krrors. 

Form  Driver.  4  (5 

FCS,  (5  29 

Defaults. 

Form  Driver  processing  of.  4  9 

displaying.  6  20.  6  21 

form  library  files,  (i  29 

^^ 

Form  P'iditor.  2  6 

Form  I'tilitv.  .'1-2 

0 

form  library  file  type,  6  14 

RMS.  H  29" 

Form  Ctility.  :\  2 

signaling  operators  about.  5  4 

supervisor  only  mode.  6  27  to  6 

28 

with  debug  mode.  5  M 

Definitions, 

Kvent  flags. 

field.  2-2 

conditionals.  5-47 

form  ilescription,  2  2 

terminal.  5  48 

form  description  file.  2-2 

Kxamples. 

Form  Kditor.  2  2 

data  entry  application.  B-1 

form  library  file.  2-2 

extended.  B-1 

screen  torm.  2   1 

Form  Editor.  2-25 

DP:LCHAK  operation.  2  14 

of  forms.  B   1 

DKI.KOL  operation.  2  14 

KXIT  SCROLLKD  ARKA  BACKWARD 

Delete  Key.  4   12 

function.  4-17 

Deleting        also  see  "erasing".  2 

14 

KXIT  S(^R()LLKD  ARKA  FORWARD 

Deleting  form  descriptions.  M  H 

function.  4   18 

DHLLINK  o()erati()n.  2   15 

Kxiracting  form  descriptions.  .'^9 

• 

Index  2 

PCS. 

error  codes,  5-2,  (i-~29 

initializing  for  Form  Driver,  5-45 

support  for  Form  Driver  resident  library, 
5-12 

support  requirements,  5   11 
FCIKTAF  call, 

techniques,  7-5 
F'ield  attributes, 

assigning,  2-7.  2-21 

Form  Driver  processing  of,  4-5 
F'ield  descriptions,  listing,  M-17 
Field  editing.  Form  Driver,  4-11 
Field  index.  5-40 
Field  length,  getting,  6-13 
Field  marker  characters,  F'orm  Driver 

processing,  4-5 
Field  names, 

assigning,  2-22 

beginning  with  "*",  6-4 

COBOL  requirements,  3-13 

Form  Driver  use  of,  4-2 

returning,  6-2 

unspecified,  6-4 
P'IF]LD  operation  and  mode.  2-10 
Field  pictures. 

Form  Driver  processing  of,  4-5 

mixed,  2-18 
Field  terminators, 

autotab,  2-23 

codes.  5-41 

in  scrolled  areas,  7-1 

processing.  6-18 

summary.  5-7 

use  of.  5-5 

validating.  6-7 

with  Form  Driver.  4-14 
Field  values. 

and  lengths.  5-16 

default,  2-23.  4-6 

inserting.  4-12 

validating.  4-6,  4-10 
Field,  definition  of,  2-2 
Field-marker  characters.  2-19 
Fields, 

"*"  names.  6-4 

completing  with  Form  Driver.  4-12 

display  all  values,  6  21 

displaying  default  values,  6  20,  6-21 

tor  passwords,  2-24 

getting  impure  area  values,  6-25 

getting  lengths  of,  6-13 

getting  values  from,  6-4.  6-7 

help,  6-23 


Fields  (Hmt.). 

indexed,  creating.  2-24 

left -justified,  display  in,  6  20 

length  returned,  4  4 

moving  to  with  Form  Driver,  4   15  to  4-16 

names,  6-2 

order  of  processing,  4-4,  6-4,  6-7 

order  of  resjjonses,  4-3 

right -justified,  display  in,  6-20 

unspecified  names,  6-4 

validating  with  Form  Driver,  4  5 
File  specifications  for  form  libraries,  6  14 
File  tyi)es. 

defaults,  3-2 

form  library  default.  6-14 
Fill  character,  assigning.  2  2.3 
Fixed  decimal  attribute. 

assigning,  2-23 

choosing  support  for,  8-7 

Form  Driver  processing  of,  4-7,  4-18 
Flashing  fields,  2-16 
FMS-11  messages.  C-l 
FMSMAC  system  macro  library,  A-1 
Form, 

definition.  2-2 
FORM  command.  2-7 
Form  description  file,  definition,  2-2 
Form  descriptions. 

block  aligned.  3-7 

converting.  .3- 10 

definition,  2-2 

deleting,  ;?-8 

extracting.  3-9 

for  COBOL  programs,  3-12 

Form  Driver  processing.  4-1 

image  map.  3-15 

listing,  3-13 

processing,  3-1 

storing  in  separate  files,  3-10 

updating  in  form  library  files,  ;?-9 
Form  Driver, 

$FDV  macro,  5-37 

$FDVDF  macro,  5-37 

and  fixed  decimal  fields.  4-18 

and  Ibrm  descriptions,  4-1 

call  status,  5-1 

calling  with  MACRO-11,  5-37 

configuration  options,  5-3 

configuration  procedure,  8-4 

control  of  cursor  by,  4-12 

debug  mode,  4-10,  5  3 

debug  mode,  choosing,  8-7 

debug  mode,  error  statu;    5-3 

erasure  operations,  4-12 


Index  '.] 


Form  Driver  (Cont.). 

field  editing  operations.  4   11 

field  terminating  functions.  4   14 

form  display  procedure.  4-2 

function  dependent  arguments,  fi  87 

HKLP  function.  4-;{ 

high  level  language  interface,  "i   14 

impure  area  requirements,  ,")   10 

keypad  operations.  4-9 

limitation  on  insertion  modes.  4-n 

messages,  (]-2'.^ 

necessary  arguments  in  calls,  fv  M7 

omitting  the  SOB  instruction.  H-6 

operator  interaction  with.  4-9 

order  of  fields,  4  4 

processing  default  field  values,  4  6 

processing  of  autotah  attrihute.  4-6 

processing  of  field  attrihutes.  4  5 

processing  of  field  markers,  4-5 

processing  of  form  text,  4-5 

processing  of  video  attributes,  4-5 

processing  operator  errors,  4-9 

repainting  the  screen,  4   11 

required  argument  list  summary.  5  .'59 

scrolled  area  moves.  4   16 

status  code.  5-;W 

summary  of  alternate  keypad 

terminators.  5-9 
summary  of  BASIC  PLl'S-'J  arguments. 

5-lH.l' 
summary  of  COBOL  arguments,  5  24 
summary  of  FCS  and  RMS  requirements, 

5   11 
summary  of  field  terminators,  5-7 
summary  of  Form  Driver  arguments,  5   15 
summary  of  FORTRAN  IV  arguments.  5-152 
summary  of  FORTRAN  IV-BLL'S  arguments, 

5-32 
summary  of  MACRO  1 1  offsets,  5-;57 
summary  of  status  codes,  5-2 
switching  insertion  modes.  4-i;i 
syntax  of  BASIC-PLUS-2  calls,  5  18. 1 
syntax  of  COBOL  calls,  5-25 
.syntax  of  FORTRAN  IV  calls.  5  ;52 
.syntax  of  FORTRAN  IV-PLCS  calls.  5  :52 
use  of  form  and  field  names,  4-2 
use  of  impure  area,  4-."? 
using  as  a  resident  library,  5   12 
validating  field  values,  4-5  to  4  6 
with  memory  resident  forms.  4   1 
Form  Kditor. 
assigning  field  attributes  with,  2-21 
assigning  form-wide  attributes.  2  20 
command  summary,  2-4 


Form  P^ditor  (Cont.). 

creating  scrolled  areas  with.  2   17 

cursor  direction  with.  2   11 

cursor  movement  with,  2-11 

edit  status  line.  2-8 

erasing  with.  2  14 

example  for.  2  25 

field  pictures.  2-18 

field-marker  characters,  2-19 

form  size  report.  2-21 

impure  area  report.  2  21 

inserting  with.  2-11.  2-i;5 

keypad  functions.  2-5 

mode-changing  operations,  2-10 

moving  fields.  2   15 

operations.  2   15 

prompts.  2-5 

size  with  RSX  systems.  2  li 

starting  with  RSX  systems.  2-.'5 

text  modifying  operations.  2- l.'i 

using  the  Return  key.  2-12 

video  attributes  with.  2  16 
P\)rm  library  directories,  size.  8-7 
Form  library  directory  buffers,  number.  8-8 
Form  library  file. 

channels  for.  ()-14 

closing.  6-12 

creating.  .'5-7 

definition.  2-2 

directory  of  forms  in.  .'5-6 

errors  with.  5-2.  6-29 

examining.  ;5-l 

file  specifications  for.  6-14 


IAN. 


:59 


number  in  use.  8-8 

opening.  6-14 

setting  channels  for.  6-11 

sharing.  6-1 1 

using.  6-11 
Form  name. 

assigning.  2-20 

P\)rm  Driver  use  of.  4-2 
Form  size,  report.  2-21 
Form  I'tility. 

defaults,  .'5  2 

errors,  ;5-.'5 

options,  .'5-4 

prompts,  .'5-1,  .'5-;5 

spooling  files,  ;5  6 

starting  and  stopping.  .'5-1 
P'orm-wide  attributes, 

assigning.  2  7.  2  20 
Forms. 

adding  to  form  library  files.  ;5  9 


Index  4 


Forms  (Cont.  I. 

creating;  object  modules  for,  3-11 
date  processed.  'A-l 
dis})laying,  6-1.  B--'2(i 
editinij.  2  7 
examples,  Hi 
for  COBOL  programs.  ;i  12 
listing  of.  ;?- 7 
memory  resident.  .'Ill 
re-initializinji.  6-21 
simultaneous  display.  7-4 
size,  ;^-7 
storinfj,  2-8 

FORTRAN  IV, 
building  applications,  o-.'l") 
F'orm  Driver  arguments,  .'i~.,. 
Form  Driver  call  syntax.  5  17.  5-.'V2 
impure  area  structure.  6  9 
summary  of  arguments,  5-15 
summary  (  f  Form  Driver  calls,  r)-.'^2 

FORTRAN  IV-PLUS. 
building  applications.  5-35 
Form  Driver  arguments,  5-.'V2 
P'orm  Driver  call  syntax.  5-17.  5-32 
summary  of  arguments.  5-15 
summary  of  Form  Driver  calls.  5-32 

Function-dependent  arguments,  5  40 


Oet  a  scrolled  area  line.  6-10 

(Jet  all  field  values.  6-7 

Get  all  field  values  from  impure  area.  6-24 

Get  any  field  value,  6-5 

Get  current  field  name.  6-2 

Get  field  value.  6-4 

Get  field  value  from  impure  area,  6-25 

Get  named  data  by  index,  6-8 

Get  named  data  by  name,  6-15 

Get  status  of  the  last  call.  6-29 

Get  the  length  of  a  field.  6-13 

Global  offsets.  Form  Driver.  5-37 


Help. 

at  the  field  level,  4-3 

display,  6-23 

for  the  application  operator,  4  3 

form  library  files,  6-11 

Form  I'tility,  3-5 

form-wide.  4-3 

messages.  4   10 
Help  for  a  field,  assigning,  2-23 
Help  form  name,  assigning.  2  20 


Help  forms. 

requirements,  7  5 
HVA.P  function. 

Form  Driver,  4-  3 
High  level  language  calls. 

FCLRSH, 6  1 

F(;(T\  6-2 

FGET,  6  4 

f(;p:taf.  6  5 

FGETAL,  6  7 

FIDATA.  6-8 

FIN  IT,  6-9 

FINLN.  6-10 

FLCHAN.  6-11 

FLCLOS.  6-12 

FLRN.  6-13 

FLOPKN.  6-14 

FNDATA.  6-15 

FOITLN.  6-16 

FPFT,  6  18 

FPUT.  6-20 

FPUTAL,  6-21 

FPITL.  6-23 

FRETAL.  6-24 

FRP:TN,  6-25 

FSHOW.  6-26 

FSPOFF,  6-27 

F'SPON,  6-28 

FSTAT,  6-29 
High  level  language  interface,  5-14 
Horizontal  indexed  attribute, 

assigning.  2-24 

Form  Driver  processing  of,  4-7 


Image  map,  3-15 
Impure  area, 

definition,  5-10 

for  simultaneous  forms,  7-4 

getting  values  from,  6-24  to  6-25 

initializing,  6-9 

pointer.  5-42 

size,  2-21,  3-7,  3-14.  4-3 

structure.  6-9 

use  by  application.  4  .3 

use  by  Form  Driver.  4-3 
Indexed  attributes,  processing  ol.  4  7 
Indexed  fields. 

creating.  2-24 

order  of.  4  4 

techniques.  7  (i 
Initialize  the  impure  area.  (i  9 
Initializing  FCS  and  RMS.  5  45 
Input  a  field  value.  6  4 


Index 


Input  all  field  values,  6-7 
Input  any  field  value,  6  5 
INSERT  mode. 

Form  Driver,  4-5 

Form  Editor,  2-lM 
INSERT  operation  and  mode,  2   11 
INSERT/OVERSTHIKE  tumtion. 

Form  Driver,  4   14 
Inserting  blank  lines,  2   14 
Inserting  characters  with  the  Form  Editor, 

2  i;? 

Inserting  field  values,  4   12 
Insertion  modes,  switching,  4   1)5 
Installation  procedures,  H  2 


-lustification  attributes,  processing  of.  4  5 


Keypad  operations. 

P'orm  Driver.  4  9 

Form  Editor.  2  5 
Keywords  MACRO-11  Form  Driver  calls, 
5-41 


Left  justified  attribute,  processing  of.  4-5 
Lett  arrow  key. 

Form  Fid  it  or.  2   12 

use  with  Form  Driver.  4  IM 
Length  of  fields  returned.  4-4 
Line  number. 

specifying,  6  26 
Line  number,  specifying,  5-40 
Linefeed  key.  Form  Driver,  4   IM 
Listing  field  descriptions.  :{   17 
Listing  form  descriptions,  '■]   IW 
Listing  named  data,  ;5-18 
LllN  —  also  see  "channels".  6  14 
Ll'N  for  form  librarv.  5  M9 


MACRO  11. 

building  applications.  5-4H 
calling  the  Form  Driver.  5  M7 
Form  Driver  call  arguments,  5  41 
Form  Driver  calls, 

FC$ALL.  6  7 

FCSANY.  6-5 

FC$(T>S.  6  12 

F(\S(\SH.  6  1 

FCSDAT.  6-8,  6-15 


MACRO-ll  (Cont.). 
F('$(;ET.  6-4 
FC.S(;S(\  6  10 
FCSLST.  6-23 
FC$OPN,  6  14 
F(\$PAL,  6-21 
FC\$PS(\  6-16 
FC$FrT.  6-20 
FCSRAL.  6-24 
FCSRTN.  6-25 
F(\SSH().  6  26 
FC$SRF,  6-27 
FCSSPN,  6-28 
FCSTRM,  6-18 
Macros,  keyword  encoded,  5  41 
Mapping  options.  8-1 
Maps, 
image.  'A   15 
named  data,  .'?-18 
video  attributes.  '■]- 16 
Media  resident  forms, 
display  |)rocedures,  4  2 
F^orm  Driver  processing,  4-1 
Memory  resident  forms, 
choosing  support  for,  8  6 
creating,  .'^-1 1 
display  procedures,  4-2 
Form  Driver  processing,  4-1 
in  COBOL  programs,  3-12 
PSEC^TS  used,  5-46 
requirements,  5-46 
task  building  for,  5-11 
Messages, 
Form  Driver,  4-9  to  4-10,  6-23 
full  listing,  C-1 
with  debug  mode,  5-3 
Mixed  pictures,  2  18 
Modes, 

supervisor  only,  6-28 
Moving  the  cursor, 

with  Form  Driver.  4-i;] 
Must  fill  attribute, 
a.ssigning.  2-23 

Form  Driver  processing  of,  4-6 
limitations,  4-6 
Must -fill  fields.  6  18 


N  picture-validation  character,  2   18 
NAMF>  command,  2-7 
Name  pointer.  5-40 
Named  data, 

creating,  2  24 

getting  by  index.  6-8 


Index  « 


Named  (lat;i  (('out.  i. 

getting  by  natiif.  fi   l."i 

map.  :\   IH 

sI)el•ityin^^  -  7 
N'iiU'  a>  |)irtiire-\ali(lali(in  tliarai  ter. 
NORMAL  (.|HTati.)ii.  L'   17 


IS 


(^iit>ii(mnairf-. 

lu'hi  attril)utes.  2  L'l 
liirm-wiclt'  attrilmlo. 
named  data.  J   _'."> 

(}\'\'\'  rummand.  2  H 


Oljject  moduU's,  treating.  •'{   II 
01)1 


n>iiii:. 


S   1(1 


Open  a  tnrm  librarw  *'■<  1  1 

Ol'FALINK  .iperatKMi.  2   I  1 

Operator  errors,  processiiii,'.    I  H 

Operator  responses,  in  must -till  tields,  H   18 

in  respotise-recjiiired  tields.  (i   IS 

symhroni/ing.  }  'A 

to  the  K(iF/l'  cal!,  ti  4 

to  the  FCJKT.XI.  call.  H  7 
Operator  responses,  syiuhroni/mi;.  ti    I 
Option^.  Form  I'tilitw  :<  4 


Ord 


er  ol  fields  reiuriied.   I    \ 


Order  o|  operator  responses.   1  ■{ 
Order  ot  |)rotessing  tields.  H  4.  ti 


O 


verlaviiur 


FMS 


ripplicatioii? 


4ti 


OVKHSIHIKF  mode. 

Form  Driver.  4  •"> 

Form  Fditor.  '2   l-i 
OXKKSTHIKF  mode.  Form  Fditor.  2   1 
OXKHSI'RIKF  operation.  2    I  1 


Ha. 


^words.  tields  lor.  2  2\ 


FASTF  operation.  2   Iti 
Picture-validation  iharaiters.  2   IS 


'ictures. 


mixed 


IS 


processed  hv  Form  Driver.   ' 


Point 


ers. 


fiata  \alue.  ")  40 


im|)ure  area.  .) 


:U) 


names. 


40 


required  arguments  list.  ')  ■'<' 


status 


block. 


:U) 


Printing  field  descriptions.  'A   17 
I'rinting  form  descriptions.  M   \'-\ 
Printing  named  data.  M  IH 
Processing  field  terminators,  ti  IS 
Processing  scrolled  areas,  7   1 


I 


rogram  sections  u 


sed  bv  FMS, 


4(i 


Programs,  examples.  H  1 

Prompts, 
Form  Fditor.  2  "i 
Form  rtilitv.  :\  1.  :\  :\ 

PSKt  TS  used  bv  '  .vIS.  T)  4(i 


He  initiali/in.j:  a  form,  (i  22 
Heinitiali/mg  ^irolled  areas,  ti   l(i 
Repainting  the  screi'ti. 
F'orm  Fditor.  2    14 


•orm 


I) 


river.    I    1  1 


I^FPFAI'  operation.  2   1.") 
Replacing  t<irms  in  libraries,  :i  i) 
Re(|uired  argument  list. 

ottset>.  •')  :iit 

pointer.  •')  -T 
Re(juiring  opeiator  responses.  2  2'^ 


Response  reijuired  attribute 
assigning. 


•)  •) 


J.I 


Form  Driver  proce»mg  ot,  4  tl 
limitat  ions.  4  (i 
Respon>e-re(|uired  tields.  t>   IS 


Restoring  erased  line; 


urn  all  tields.  (i  24 


!.") 


Ret 

RF/riRN  limit  ion.  4   14 

F^eturn  key,  using  with  thi'  Form  Kditor. 

2   12 
Return  the  speiitied  tield.  fi  2") 
Rever.sr-  screen,  as  a  lorm-uide  attribute, 

2  20 
F'{eversed  video  tields.  2   Hi 
Right  justilied  att  ribute. 

assigning.  2  22 

Form  l)ri\er  processing  ot.  4  ."> 
Right  arrow  key. 

Form  Fditor.  2    12 

use  with  Form  Driver.  4   1-i 
RMS. 

error  codes.  ;"> 


(i  ■-.;» 


initiali/ing  tor  Form  Driver.  .V  4.") 
support  re(|uirements.  .">    1  1 
Running  F.MS  applications  under  IAS.  8   11 


S.-\\F  idinmand.  2  S 
Screen    repainting.  2   14 
SCHOFF  operation.  2   17 
Scrolled  iirea. 

cameling.  2  17 

choosing  support  lor.  S 

creating.  2   17 

cursor  motion  in.  4   Hi 


Index  7 


Scrolled  area  (Cont.i. 

defaults.  6  l(i 

displa\'  ill.  ()  ]() 

Form  Driver  processing  -)!.  4  S 

getting  values  from,  (i  10 

processing,  iv-'l.  (v  IS,  7    1 

re-initiali/ing.  (i   l(i 

recpiirements  tor.  4  8 

technicjues  for.  7  12 

valid  Form  Driver  calls  for.  7  2 
SKLKCr  operation.  2  I'l 
Setting  a  form  library  channel.  ()   11 
Sharing  form  library  files,  (i   1 1 
Size. 

field,  (i   \:\ 

form  library  directories.  8  7 

impure  area.  .'^  7.  MM.  A  -I.  o  10 
SOB  instruction,  omitting  from 

Form  Driver.  8  (i 
Spooling,  with  Form  I'tility.  M  (i 
Starting  line  numl)er.  (i  2H 
Starting  line,  assigning.  2  21 
Status  block  pointer,  .")  ;U) 
Storiiig  torm  descriptions.  2  8 
Summaries. 

alternate  keypad  terminators.  .")  ^) 

BASIC   PLl'S  2  calls.  T,  21 

BASIC   PLl'S  2  Form  Driver  arguments. 

r)-i8.i 

COBOL  calls.  0-25 

COBOL  Form  Driver  arguments,  o  24 

FCS  and  RMS  requirements,  oil 

field  terminators.  o-7 

field-marker  characters.  2   19 

form  display  procedures.  4  2 

Form  Driver  arguments.  5   15 

Form  Driver  call  status  codes.  5-2 

Form  [driver  field  editing  operations.  4   11 

Form  Kditor  commands.  2  4 

Form  Kditor  operations.  2   11 

Form  I'tility  defaults.  :V-2 

Form  I'tility  options.  M  4 

FORTRAN  IV  calls.  5  :V2 

FORTRAN  IV  Form  Driver  arguments.  5  :^2 

FORTRAN  IV  PLCS  calls.  5  :?2 

FORTRAN  IV  PLCS  Form  Driver  arguments. 

5  ;52 
high  level  language  arguments.  5  41 
MACRO   11  Form  Driver  arguments,  5  41 
MACRO   1 1  Form  Driver  function  codes,  5  ;W 
MACRO   11  offsets  for  Form  Driver.  5  :r 
picture-validation  characters.  2  18 
re(|uired  argument  list.  5  :U) 
video  attributes.  2   K).  iCKi 


Supervisor  only  attribute, 


assignuig. 


4 


Form  Driver  processing  of,  4  8 
Supervisor  only  mode, 

turning  off,  ti  27 

turning  on.  (v  28 
Switches         seeojjtions.  M  4 
Switching  torm  library  channels. 
Synchronizing  task  and  operator, 
.System  generation  options,  8   1 
Svstem  macro  librarv  (FMSMA( 


(>   11 
(i  4 

').  A-1 


TAB  function,  4   15 
Terminal  service, 

choosing  sui)port  for.  8  1) 

conditionals  tor.  5-47 

o|)tions.  8   1 
Terminating. 

a  form.  4-14 

scrolled  areas.  4-17 
Terminating  scrolled  areas. 

Form  Driver.  4   18 
Terminators. 

fields.  4-14,  5  5.  (M9 

MA(TU)  11  codes.  5  :i8 
TF'XT  operation  and  mode.  2  10 
Text. 

Form  Driver  processing.  4-5 
TOP  operation.  2-\'.\ 
Turn  oft  supervisor  only  mode,  (v  27 
I'urn  on  supervisor  only  mode,  6-28 
Typeahead.  preserviiig.  5-4(3 


\'W  in  form  library  specifications.  6-14 
Cnderline  ojjeration.  2-15 
Cnderlined  fields.  2   16 
I'parrow  key. 

Form  Driver.  4   16 

P\)rm  Kditor.  2   11 
Updating  forms  in  libraries.  .'V  9 


X'alidating  field  values.  4  6 
Validation. 

field  values.  4   10 

of  output  data,  (i   l(i,  (i  21 
Vertical  indexed  attribute. 

assigning.  2  24 

Form  Driver  processing  ol,  4  7 


Index  S 


Video  attributes. 

assigning,  2-16 

clearing.  2-17 

codes.  ,'?~16 

Form  Driver  processing  of.  4  5 

map.  3-16 

use  by  the  Form  Driver.  6-2:? 
VIDFiO  operation.  2-16 
VTlOO  alternate  keypad  mode,  4-12,  5  9 
V'r52  terminals,  using.  8-7 


Wide  screen,  as  a  ibrm-wide 
attribute.  2-20 


X  picture-validation 
character,  2-18 

Zero  fill  attribute, 
assigning,  2-2:? 
Form  Driver  processing  of.  4-6 


Index  \) 


FMS/KS\/1AS 

Software  Helereiue  Manual 

AD-H8rv,A  ri 


READER'S  COMMENTS 


NOTK:  Thi.-,  .''irm  is  for  document  eonimeiits  only.  DKHTAL  will  use  comments  submitted  on  this  form  at  the 
.(impany  -^  discretion.  II  you  require  a  written  reply  and  are  eh^ihle  to  receive  one  under  Soltware 
."ertormanct  Report  (Sl'H)  service,  submit  your  lomments  on  an  Sl'H  form. 


Did  you  find  this  manual  understandable,  usable,  and  well-organized'.'  Please  make  suggestions  Cor  imi)rovement. 


Did  you  find  errors  in  this  manual"'  If  so,  specify  the  error  and  the  page  number. 


Please  indicate  the  type  of  user/reader  that  you  most  nearlv  reijresenf. 


[J  Assembly  language  programmer 

[;  Higher  level  language  programmer 

L;  Occasional  programmer  (experienced) 

D  I'ser  with  little  programming  experience 

□  Student  programmer 

G  Other  (please  si)ecify)     


Nanu 


Organization 


Date 


Street 


Cilv 


State. 


Zip  Code 
or  Country 


—    —    —    Do  Not  Tear  -  Fold  Here  and  Tape 


SDIDDSD 


No  Postage 

Necessary 

if  Mailed  in  the 

United  States 


BUSINESS  REPLY  MAIL 

FIRST  CLASS  PERMIT  N0.33  MAYNARD  MASS. 


POSTAGE  WILL  BE  PAID  BY  ADDRESSEE 


BSSG  SOFTWARE  PUBLICATIONS  ML  5-5/E45 

DIGITAL  EQUIPMENT  CORPORATION 

146  MAIN  STREET 

MAYNARD,  MASSACHUSETTS     01754 


—    —    —    Do  Not  Tear  -  Fold  Here 


c 


c 

DC 

c 
o 


3 


